@salesforce/afv-skills 1.24.0 → 1.26.0

package/skills/platform-trust-archive-manage/SKILL.md

@@ -20,33 +20,31 @@ Operate Salesforce Archive (also called Trusted Services Archive) through its Co
 
 Gather or infer before acting:
 
-- **Operation intent**: search, view, unarchive, analyze, mask, RTBF, storage check, or job-status/log lookup.
+- **Operation intent**: search (this is also how you view archived records), unarchive, analyze, mask, RTBF, storage check, or job-status/log lookup.
 - **Target sObject** (`sobjectName`): required for search and unarchive.
 - **Filters**: search and unarchive require `sobjectName` + at least one filter.
 - **For log downloads**: the `requestId` (an `ArchiveActivity` Id, `8qv…` prefix) of a completed, log-producing job, and `reportType` = that activity's `Type`.
 
 Preconditions (confirm or surface to the user if a call returns a not-permitted error):
-- The **org** must have Salesforce Archive enabled (the `TrustedServicesArchive` / `TrustedServicesArchiveBt` org permission). Every operation is gated on this first.
+- The **org** must have Salesforce Archive enabled. Every operation is gated on this first.
 - Each operation requires a **specific user permission** on top of the org gate — see the Permissions table below. There is no single "archive admin" role; access is per-capability.
 
 ---
 
 ## Permissions
 
-Every operation first requires the org to have Salesforce Archive enabled (`hasTrustedServicesArchive` = `OrgPermissions.TrustedServicesArchive || TrustedServicesArchiveBt`). On top of that org gate, each capability is gated by a distinct **user permission**. A call the user isn't permitted for fails with a "not permitted" error — match the error to the missing permission below.
+Every operation first requires the org to have Salesforce Archive enabled. On top of that org gate, each capability is gated by a distinct **user permission**. A call the user isn't permitted for fails with a "not permitted" error — match the error to the missing permission below.
 
 | Operation | User permission required |
 |-----------|--------------------------|
-| `search-archived-records`, `get-search-archived-records-next-page` | `ViewSearchPage` (Archive Search) — the Connect search endpoint runs the global-search path, gated by Archive Search, **not** `ViewArchivedRecords` |
-| `search-archived-records-with-sharing-rules` (Agentforce) | `ViewArchivedRecords` |
+| `search-archived-records`, `get-search-archived-records-next-page` | `ViewSearchPage` (Archive Search) — **not** `ViewArchivedRecords` |
+| `search-archived-records-with-sharing-rules` | `ViewArchivedRecords` |
 | `unarchive-records` | `UnarchiveSdk` |
 | `forget-archived-records` (RTBF) + `get-rtbf-status` | `Rtbf` |
 | `mask-archived-records` + `get-masking-status` | `Rtbf` (masking shares the same `Rtbf` permission — **not** a separate entitlement) |
 | `run-analyzer`, `get-analyzer-report`, `get-archive-storage-used` | `ArchiveAnalyzer` |
 | `get-execution-details-stream-url`, `get-failed-records-stream-url` | `ViewActivitiesPage` (Archive Activities) |
 
-> Source of truth: the Connect API resource classes in `trusted-services-archive-connect-impl` → `TrustedServicesArchiveSdkImpl` guards → `TrustedServicesArchive.accessChecks.xml`. Note `search-archived-records` routes through `performArchiverGlobalSearch` (gated by `canRunArchiveSearch` = `ViewSearchPage`); the separate Apex-SDK `searchArchivedRecords()` method is gated by `ViewArchivedRecords`, but the **Connect API** search endpoint does not use it.
-
 ---
 
 ## Workflow
@@ -57,7 +55,24 @@ All steps are sequential within a task. Read the referenced file the first time
 
 2. **For job status / monitoring, read the data model** — when the task involves archive jobs, failures, progress, counts, or logs, load `references/archive-activity-entity.md` for the `ArchiveActivity` field reference and how it links to the Connect API. Query `ArchiveActivity` via SOQL or Connect — **not** Flow. For a worked end-to-end example (find failed/in-progress jobs, then pull their execution-detail and failed-records logs), load `examples/monitor-failed-jobs.md`.
 
-3. **Construct and send the call** — follow the contract exactly. For searches, supply `sobjectName` + ≥1 filter; for date filtering use the plural `dateRanges` array of `{field, from, to}` with full ISO-8601 datetimes.
+3. **Construct and send the call** — every operation is a `{method, path, body}` REST call. Send it with whatever Connect/REST API tool your environment provides (an MCP server that invokes Connect/REST APIs, the `sf` CLI, or any REST client). Two path rules are critical (full per-operation contracts are in `references/connect-api-operations.md`):
+
+   - **The operation names in this skill are NOT URL paths.** `search-archived-records`, `unarchive-records`, etc. are labels; never put them in the path. Use the short literal paths below (each relative to base `/platform/data-resilience/archive`). Sending the operation name as a path segment (e.g. `/…/archive/search-archived-records`) returns **404**.
+   - **The path stops at `/platform/data-resilience/archive/…` — there is NO `/connect` segment**, even though this is a Connect API. A **404 / `NOT_FOUND` here means the path is wrong, NOT that Archive is disabled** — fix the path before concluding the add-on is missing.
+
+   | Operation | Method + Path | Notes |
+   |-----------|---------------|-------|
+   | search-archived-records | `POST /search` | requires `sobjectName` + ≥1 filter |
+   | search next page | `GET /search/next/{scrollId}` | stop when `scroll_id == "-1"` |
+   | search with sharing rules | `POST /search/with-sharing-rules` | uses `filtersJson` object map |
+   | unarchive-records | `POST /unarchive` | `sobjectName` + filters |
+   | run-analyzer / report | `POST /analyzer/run` · `GET /analyzer/report` | |
+   | forget / RTBF + status | `POST /rtbf` · `GET /rtbf/{requestId}` | |
+   | mask + status | `POST /mask` · `GET /mask/{requestId}` | |
+   | storage used | `GET /storage/archive-used` | |
+   | execution-detail / failed-records log | `GET /log/execution-details-stream-url` · `GET /log/failed-records-stream-url` | query params `requestId`, `reportType` |
+
+   With the `sf` CLI, prefix the path with `/services/data/v67.0`; some MCP/REST tools take the bare path and add the version themselves (tool-dependent — see the reference). Then follow the contract: for searches, supply `sobjectName` + ≥1 filter; for date filtering use the plural `dateRanges` array of `{field, from, to}` with full ISO-8601 datetimes.
 
 4. **Branch on the right signal** — some operations return HTTP 201 with a body-level success flag (`body.statusCode`, `body.isSuccess`). Read `references/connect-api-operations.md` for which signal to trust per operation; never assume the HTTP status alone means success.
 
@@ -80,12 +95,11 @@ All steps are sequential within a task. Read the referenced file the first time
 
 | Constraint | Rationale |
 |-----------|-----------|
-| Search & unarchive require `sobjectName` + at least one filter | The controller rejects an unfiltered request with "Search must be based on at least 1 field" — a full-object operation is never allowed. |
+| Search & unarchive require `sobjectName` + at least one filter | An unfiltered request is rejected with "Search must be based on at least 1 field" — a full-object operation is never allowed. |
 | Date filters must be full ISO-8601 datetimes (`2020-01-01T00:00:00Z`) | A date-only value (`2020-01-01`) returns `400 JSON_PARSER_ERROR` because the field is typed `xsd:dateTime`. |
 | Search uses `dateRanges` (plural array); unarchive uses `dateRange` (singular) | They are genuinely different fields on the two endpoints; using the wrong shape silently drops the filter or 400s. |
 | Stop pagination when `scroll_id == "-1"` | Calling `get-search-archived-records-next-page` with `"-1"` returns 500. |
 | Log downloads need a real `ArchiveActivity` Id as `requestId` + that activity's `Type` as `reportType` | The backend resolves the log by the activity record; a mismatched `reportType` returns no log. |
-| Never use the deprecated lookups | `global-search-by-id`, `get-global-search-results`, and `view-archived-records` are deprecated with no successor and currently 500. Use `search-archived-records` (+ next-page) instead. |
 | Excluded objects are not retrievable | `Feed`, `History`, `Relation`, `Share` are not searchable; Files/Attachments are not retrievable via this API — do not promise them. |
 | Query `ArchiveActivity` via SOQL/Connect, never Flow | `ArchiveActivity` has `isProcessEnabled=false`, so a Flow "Get Records" element on it fails with "You can't get ArchiveActivity records in a flow." |
 
@@ -97,7 +111,7 @@ All steps are sequential within a task. Read the referenced file the first time
 |-------|------------|
 | Treating HTTP 201 as success | Several operations return 201 with a body-level outcome. Branch on `body.statusCode` (search) or `body.isSuccess` (`with-sharing-rules`), not the HTTP code. |
 | `run-analyzer.isRunning` used as a signal | It is **always** `null`; the endpoint only populates `message`. Poll `get-analyzer-report` to confirm completion instead. |
-| `search-archived-records-with-sharing-rules` (Agentforce) filters as an array | `filtersJson` must be a JSON-encoded **object map** `{"Field":"Value"}`, not an array of `{field,value}`; the array form returns `isSuccess:false "No valid filters provided"`. |
+| `search-archived-records-with-sharing-rules` filters as an array | `filtersJson` must be a JSON-encoded **object map** `{"Field":"Value"}`, not an array of `{field,value}`; the array form returns `isSuccess:false "No valid filters provided"`. |
 | Log `url` treated as present because status is 201 | `get-*-stream-url` returns `{url}`; `url: null` means no log was resolved. Always check `url != null`. |
 | Misreading `get-archive-storage-used` | `usedStorage[]`/`availableStorage[]` are parallel positional arrays: index 0=org DATA, 1=org FILE, 2=archive RECORDS, 3=archive FILE. `availableStorage[2]`/`[3]` are **always 0** (archive tier is unmetered) — that means "not tracked", not "full". |
 | Expecting `ArchiveActivity` in a Flow | It is not Flow-enabled (`isProcessEnabled=false`). Use SOQL/Connect/Reports. |

package/skills/platform-trust-archive-manage/examples/monitor-failed-jobs.md

@@ -23,13 +23,13 @@ Read each row's `ProgressPercentage`, `SucceededCount`/`FailedCount`, `RootEntit
 Take the job's `Id` (`8qv…`) as `requestId` and its `Type` as `reportType`. `{activity.Type}` below is a placeholder for that job's own `Type` field value (e.g. `Archive`, `Purge`, `Unarchive`, `Analyzer`) — substitute the actual value per job; a hardcoded/mismatched `reportType` returns no log.
 
 **Execution-detail log:**
-```
+```text
 GET /platform/data-resilience/archive/log/execution-details-stream-url
     ?requestId={activity.Id}&reportType={activity.Type}
 ```
 
 **Failed-records log:**
-```
+```text
 GET /platform/data-resilience/archive/log/failed-records-stream-url
     ?requestId={activity.Id}&reportType={activity.Type}
 ```

package/skills/platform-trust-archive-manage/references/archive-activity-entity.md

@@ -10,7 +10,7 @@
 | Key prefix | `8qv` (record Ids start `8qv…`) |
 | Owning product | Salesforce Archive (Trusted Services Archive) |
 | Kind | **Standard platform entity** (not a custom object) |
-| License gate | Requires the Trusted Services Archive add-on (`TrustedServicesArchive.hasTrustedServicesArchive`) — absent on orgs without the add-on |
+| License gate | Requires the Trusted Services Archive add-on — absent on orgs without the add-on |
 | Name field | Auto-number, mask `ARCV-{0000000000}` |
 | Flow-enabled? | **No** — `isProcessEnabled=false`. A Flow "Get Records" element on it fails: "You can't get ArchiveActivity records in a flow." Query via SOQL / Connect / Reports. |
 

package/skills/platform-trust-archive-manage/references/connect-api-operations.md

@@ -1,13 +1,54 @@
 # Salesforce Archive Connect API — Operations Reference
 
-All operations are under the base path `/platform/data-resilience/archive/`. Contracts verified live against archived data. Read the operation you need before constructing the call — several contracts are non-obvious.
+Read the operation you need before constructing the call — several contracts are non-obvious.
+
+## How to call these operations
+
+Every operation is a REST call defined by three things:
+
+- **method** — `GET` or `POST` (see the `Method + Path` column below)
+- **path** — the resource path, e.g. `/platform/data-resilience/archive/search`
+- **body** — a JSON object (POST only); GET operations carry their inputs as query-string params and send no body
+
+```text
+{method} /platform/data-resilience/archive/{operation-path}
+```
+
+The `/platform/...` path *is* the complete resource path — there is **no `/connect` segment** and you do not append the operation name (details below). Use API version `67.0`.
+
+**Send it with whatever Connect/REST API tool your environment provides** — an MCP server that invokes Connect/REST APIs, the `sf` CLI, or any REST client. Map the three primitives above to that tool's parameters.
+
+**Whether the path needs the `/services/data/v67.0` prefix depends on the tool, not on MCP-vs-CLI** — some tools want the full versioned URL, others take the bare `/platform/...` path and add the version/host themselves. Check the tool's own docs; if a bare path returns `NOT_FOUND`, try the full versioned form (and vice-versa).
+
+**If using the `sf` CLI** — supply the **full versioned URL** and pass the body inline. The `--body` flag takes the JSON itself, **not** a filename (a bare filename is sent verbatim → `JSON_PARSER_ERROR`):
+
+```bash
+sf api request rest "/services/data/v67.0/platform/data-resilience/archive/search" \
+  --method POST \
+  --body '{"sobjectName":"Account","filters":[{"field":"Name","value":"salesforce.com"}],"fields":["Id","Name","Phone"]}' \
+  --target-org <org-alias>
+```
+
+**If using an MCP server / other REST client** — map method, path, and body to its parameters (names vary per tool; check its docs). For example, the body for the same search is:
+
+```text
+{"sobjectName":"Account","filters":[{"field":"Name","value":"salesforce.com"}],"fields":["Id","Name","Phone"]}
+```
+
+(For GET operations, append the inputs as query-string params on the path and send no body.)
+
+> Two path rules that otherwise surface as a misleading error, **regardless of how you send the call**:
+> - **Use the literal path from the `Method + Path` column below — never build one from the operation name.** The operation identifiers in this doc (`search-archived-records`, `unarchive-records`, …) are *names*, not URL segments. The real path is short and rarely matches the name: `searchArchivedRecords` → `POST /search` (NOT `/search-archived-records`), `unarchiveRecords` → `POST /unarchive`, `getArchiveStorageUsed` → `GET /storage/archive-used`. Synthesizing the path from the operation name (e.g. kebab-casing it and appending it) produces a route that returns **404** even though the operation exists. Always copy the path string verbatim from the table.
+> - **The path stops at `/platform/data-resilience/archive/...`** — there is no `/connect` segment, even though this is a Connect API. Inserting one returns `NOT_FOUND` for the whole namespace, which can read as "Archive is disabled" — it isn't; it's the path.
 
 ## Operations Summary
 
-| Operation | Purpose | Method + Path | Verify with |
+The first column is the **operation name** used to refer to each op in this skill — it is **not** part of the path. The method and path to send are in the **Method + Path** column; each path shown (e.g. `POST /search`) is shorthand for `POST /platform/data-resilience/archive/search`.
+
+| Operation (name only — NOT a path segment) | Purpose | Method + Path (send THIS) | Verify with |
 |-----------|---------|---------------|-------------|
 | `search-archived-records` | read | `POST /search` | — |
-| `search-archived-records-with-sharing-rules` | read (Agentforce) | `POST /search/with-sharing-rules` | — |
+| `search-archived-records-with-sharing-rules` | read | `POST /search/with-sharing-rules` | — |
 | `get-search-archived-records-next-page` | read | `GET /search/next/{scrollId}` | — |
 | `run-analyzer` | write | `POST /analyzer/run` | `get-analyzer-report` |
 | `get-analyzer-report` | read | `GET /analyzer/report` | — |
@@ -20,8 +61,6 @@ All operations are under the base path `/platform/data-resilience/archive/`. Con
 | `get-failed-records-stream-url` | read | `GET /log/failed-records-stream-url` | — |
 | `get-archive-storage-used` | read | `GET /storage/archive-used` | — |
 
-**Deprecated — do not use** (no successor; currently 500): `global-search-by-id`, `get-global-search-results`, `view-archived-records`. Use `search-archived-records` (+ `get-search-archived-records-next-page`) for all archived-record lookups.
-
 ### Verify-after-write dependencies
 
 ```mermaid
@@ -44,12 +83,12 @@ Search archived records by object, filters, date ranges, and sort.
 - `sobjectName` *(string)* — API name of the sObject to search.
 - `filters` *(array)* — Filter conditions, each `{field, value}` where **both are required strings**. `value` is a single string — **not** an array, **not** nullable (null/omitted → `400 "This field may not be null"`). There is **no `operator` field**. **At least 1, up to 6 filters, combined with AND only** (OR is not supported). Example: `[{"field":"Subject","value":"Foo"}]`.
 - `dateRanges` *(array)* — Primary date filter: array of `{field, from, to}`. `from`/`to` must be full ISO-8601 datetime (`"2020-01-01T00:00:00Z"`); date-only → `400 JSON_PARSER_ERROR` (xsd:dateTime). Use the special field `archive_date` to filter by archive date instead of `CreatedDate`/`ModifiedDate`.
-- `dateRange` *(object)* — Optional **singular** convenience range `{field, from, to}`; the controller folds it into `dateRanges` (one-element equivalent). Same singular shape that `unarchive-records` uses.
+- `dateRange` *(object)* — Optional **singular** convenience range `{field, from, to}`; treated as a one-element `dateRanges`. Same singular shape that `unarchive-records` uses.
 - `fields` *(array)* — Field API names to return.
 - `pageSize` *(integer)* — Records per page; default 25, max 1000.
 - `sortDirection` *(string)* — `asc`/`desc`, case-insensitive, default `asc`; an invalid value → 400.
 
-**Output**: HTTP **201**, `body = { records[], total_result_count, scroll_id }`, `body.statusCode = 200`, `errorMessage` null on success. **Branch on `body.statusCode`, not the HTTP code** — once past framework validation the response is always 200/201 even on logical failure, with the error in `errorMessage` + `statusCode`.
+**Output**: HTTP **201**, `body = { records[], total_result_count, scroll_id }`, `body.statusCode = 200`, `errorMessage` null on success. **Branch on `body.statusCode`, not the HTTP code** — once past request validation the response is always 200/201 even on logical failure, with the error in `errorMessage` + `statusCode`.
 
 **Excluded objects**: `Feed`, `History`, `Relation`, `Share` are not searchable; Files/Attachments are not retrievable.
 
@@ -66,7 +105,7 @@ Read records inline from each response. If `body.scroll_id != "-1"`, call `get-s
 
 ## search-archived-records-with-sharing-rules (`POST /search/with-sharing-rules`)
 
-Archive search **optimized for Agentforce agents**. (There is no `/search/related` endpoint — this is the operation that takes the JSON filter map.) Gated by the **`ViewArchivedRecords`** user permission (unlike plain `search-archived-records`, which uses `ViewSearchPage`).
+Archive search that enforces the user's sharing rules. (There is no `/search/related` endpoint — this is the operation that takes the JSON filter map.) Gated by the **`ViewArchivedRecords`** user permission (unlike plain `search-archived-records`, which uses `ViewSearchPage`).
 
 **Required**: `objectName`, `filtersJson`.
 
@@ -83,7 +122,7 @@ Archive search **optimized for Agentforce agents**. (There is no `/search/relate
 
 ## run-analyzer (`POST /analyzer/run`) + get-analyzer-report (`GET /analyzer/report`)
 
-`run-analyzer` triggers the analyzer; HTTP 201, output `message` *(string, human-readable status)*. **`isRunning` is ALWAYS `null`** — the controller only populates `message`; never branch on `isRunning`. Poll `get-analyzer-report` to confirm completion. Non-destructive / idempotent.
+`run-analyzer` triggers the analyzer; HTTP 201, output `message` *(string, human-readable status)*. **`isRunning` is ALWAYS `null`** — only `message` is populated; never branch on `isRunning`. Poll `get-analyzer-report` to confirm completion. Non-destructive / idempotent.
 
 `get-analyzer-report` returns `body` with: `topRecords[]` (`{objectName, objectLabel, objectIcon, size, count, usagePercent}` per archivable sObject), `topFiles[]` (parallel shape for files), `fileGeneralStorage`/`dataGeneralStorage` (`{storageUsed, storageRemaining, usagePercent}`), and `createdDateReport` (`"DD/MM/YYYY HH:MM:SS"`).
 
@@ -96,7 +135,7 @@ Restore archived records back into live storage by criteria.
 **Inputs**:
 - `sobjectName` *(string)* — sObject whose records to unarchive.
 - `filters` *(array)* — criteria identifying which archived records to restore.
-- `dateRange` *(object)* — optional **SINGULAR** range `{field, from, to}` (reads `getDateRange()`, unlike `/search` which uses plural `dateRanges`); full ISO-8601 datetimes. Omit to unarchive by filters alone.
+- `dateRange` *(object)* — optional **SINGULAR** range `{field, from, to}` (unlike `/search`, which uses the plural `dateRanges`); full ISO-8601 datetimes. Omit to unarchive by filters alone.
 
 **Caps**: ≤1000 matched records (else not processed); ≤50 unarchive requests/hour/org. Restores the **whole archived hierarchy** of each match. Requires the **`UnarchiveSdk`** user permission (on top of org-level Archive enablement).
 
@@ -122,7 +161,7 @@ Submits a PII-masking (anonymization) request — irreversibly replaces detected
 
 **Behavior**: permanent; one-time per record (re-requests on an already-masked record are ignored); shares the 10,000/day RTBF rate limit; **PII fields are auto-detected** (you cannot choose them); records under legal hold / retention lock are excluded; cascades to child records. Available **only via this API** (not in the Archive UI).
 
-**Permission**: gated by the **`Rtbf`** user permission — the SAME permission as RTBF (`maskArchivedRecords` runs the RTBF access check), not a separate masking entitlement.
+**Permission**: gated by the **`Rtbf`** user permission — the SAME permission as RTBF, not a separate masking entitlement.
 
 **Output**: HTTP 201, `body.request_id` *(UUID)*. Poll `get-masking-status` (path param `requestId`); status reaches **HANDLED** when complete. **Rollback**: none — anonymization is permanent.
 
@@ -154,4 +193,4 @@ Returns `body.usedStorage[4]` (doubles — per-tier bytes consumed) and `body.av
 | 2 | Archive-tier **RECORDS** storage |
 | 3 | Archive-tier **FILE** storage |
 
-**`availableStorage[2]` and `[3]` (the archive tier) are ALWAYS 0**: the controller hardcodes them (`ARCHIVER_AVAILABLE_STORAGE = 0`) because archive storage is unmetered, so a `0` there means "not tracked", NOT "no space left". Only `availableStorage[0]`/`[1]` (live org data/file remaining) are real. All values rounded to 2 decimals.
+**`availableStorage[2]` and `[3]` (the archive tier) are ALWAYS 0**: archive storage is unmetered, so a `0` there means "not tracked", NOT "no space left". Only `availableStorage[0]`/`[1]` (live org data/file remaining) are real. All values rounded to 2 decimals.

package/skills/analyzing-test-failures/SKILL.md

@@ -1,159 +0,0 @@
----
-name: analyzing-test-failures
-description: "Parses a DevOps Center test-failure or Code Analyzer violation payload and explains it in plain language — failure category, offending file/class/method/line, rule violated, and fix direction — then gives prioritized test-improvement suggestions (distinguishing test-code from production-code fixes). Pure reasoning: no system calls or code authoring. TRIGGER when: a test run failed and the user wants root cause; a quality gate failure needs explaining; Code Analyzer violations need translating to plain language; the user shares a failure payload and asks how to address it; tests keep failing and the user wants suggestions; or the user wants to close coverage gaps, strengthen assertions, or fix flaky/weak tests. DO NOT TRIGGER when: the user wants fix code written (use platform-apex-generate) or new test classes authored (use platform-apex-test-generate)."
-metadata:
-  version: "1.0"
-  minApiVersion: "67.0"
----
-
-# analyzing-test-failures
-
-**Type:** Pure reasoning — no system calls, no code authoring.
-
-**What it does:** Parses a test failure or Code Analyzer violation payload and produces a plain-language explanation, then follows up with concrete, prioritized improvement suggestions per failed test — including whether each fix belongs in the test or in production code. Never exposes raw JSON, stack traces, or API error bodies to the user.
-
----
-
-## Prerequisites
-
-If you need to fetch the failure payload yourself rather than receiving it, load `checking-devops-prerequisites` first, then use `polling-test-results` to obtain the execution result. If the payload is already in context, no prerequisites are needed — this is pure reasoning.
-
----
-
-## Inputs
-
-- JSON failure payload provided by the `polling-test-results` skill, or pasted directly into context from a test run or Code Analyzer execution. Specifically required per failed test:
-  - Test method name
-  - Failure message (the assertion error or exception text)
-  - Failure category (assertion failure, unhandled exception, timeout, compile error)
-
----
-
-## Empty-org / no-data case
-
-If the payload contains no failures or violations, report that clearly (e.g. "No failures found in the provided execution results.") and stop. Do NOT fabricate failures, violations, or improvement suggestions when none are present.
-
----
-
-## Reasoning steps
-
-1. Determine the failure category:
-
-   | Category | Description |
-   |---|---|
-   | **Assertion failure** | A test assertion failed (expected vs actual mismatch) |
-   | **Exception** | An unhandled exception was thrown |
-   | **Code Analyzer violation** | A static analysis rule was violated (e.g. `ApexCRUDViolation`, `ApexSharingViolations`) |
-   | **Timeout** | Test exceeded execution time limit |
-   | **Compile error** | Class failed to compile |
-
-2. For each failure, extract and translate to plain language:
-   - Offending file and class name
-   - Method name
-   - Line number
-   - What rule or assertion was violated, in plain language
-   - Suggested fix direction (without writing code)
-
-3. Group failures by category if more than one.
-
----
-
-## Output format
-
-```text
-Test failure summary:
-
-<N> failure(s) found:
-
-1. [<Category>] `<ClassName>.cls` — `<methodName>()` at line <N>
-   What happened: <plain-language description>
-   Rule violated: <ruleName or assertion description>
-   Fix direction: <plain-language suggestion>
-
-2. [<Category>] `<ClassName2>.cls` — `<methodName2>()` at line <N>
-   ...
-```
-
----
-
-## Code Analyzer violations
-
-For violations, always include:
-- The rule name translated to plain English (e.g. "ApexCRUDViolation" → "A SOQL query was made without checking object-level permissions first")
-- The exact line number
-- The fix direction (e.g. "Add a `Schema.sObjectType.Account.isAccessible()` check before the query")
-
----
-
-## Plain-language rule
-
-Never paste raw stack traces, JSON payloads, or internal Salesforce error codes into the output. Always translate to file name, method, line, and plain description.
-
----
-
-## Suggesting improvements
-
-Invoke this section **after test execution completes with failures**, not on static source code. The failure message is the primary signal — it describes what the test expected vs. what actually happened, which directly informs what the test needs to handle better.
-
-### 1 — Read each failure message
-
-For each failed test in the execution result, extract:
-- Test method name
-- Failure message (the assertion error or exception message)
-- Failure category (assertion failure, unhandled exception, timeout, compile error)
-
-### 2 — Infer what the test is not handling
-
-Reason over the failure message to identify the root cause pattern:
-
-| Failure pattern | Improvement suggestion |
-|---|---|
-| `NullPointerException` | The test is not handling null input — add a null check or a test setup that ensures the data exists |
-| `Assertion failed: expected X but was Y` | The expected value in the assertion is wrong or the test data setup does not produce the right state |
-| `List has no rows for assignment` | The test is querying for data that doesn't exist — test setup is incomplete |
-| `System.LimitException: Too many SOQL queries` | The test is hitting governor limits — the code under test or test setup is making too many queries |
-| `Insufficient access rights on cross-reference id` | The test user lacks the required permissions — the test needs to run as a user with appropriate profile/permission set |
-| `DML currently not allowed` | The test is performing DML inside a method called from a context that doesn't allow it |
-| Code Analyzer violation message | The production code violates a specific rule — the test exposed it but the fix is in the production code, not the test |
-
-### 3 — Produce actionable suggestions
-
-For each failure, describe in plain language:
-- What the failure reveals about what the test is not handling
-- What specifically should be added or changed to make the test robust
-- Whether the fix is in the **test** (assertion, setup, permissions) or in the **production code** (the test is correct but the code under test is broken)
-
-Do not rewrite the test. Only describe what needs to change and why.
-
-### Output format for improvements
-
-```text
-Test improvement suggestions based on execution results:
-
-`<testMethodName>()` — [Assertion Failure / Exception / etc.]
-Failure: "<failure message>"
-What this reveals: <plain-language explanation>
-Suggestion: <specific, actionable recommendation>
-Fix location: Test | Production code
-
-`<testMethodName2>()` — [NullPointerException]
-Failure: "Attempt to de-reference a null object"
-What this reveals: The test is calling the method without setting up the required input data
-Suggestion: Add test data setup for <object/field> before calling the method
-Fix location: Test
-
-Overall: <N> improvement(s) across <M> failed test(s).
-```
-
-### Test fix vs. production-code fix
-
-Suggestions flagged as **Fix location: Production code** indicate a code defect exposed by the test — the test logic itself is sound. These should not block suite promotion on the grounds of test quality; they should be tracked separately as production defects.
-
-Suggestions flagged as **Fix location: Test** indicate the test needs to be hardened — missing setup, wrong assertions, inadequate coverage of edge cases (null inputs, bulk record volumes, mixed permission contexts, governor-limit boundaries).
-
----
-
-## Related skills
-
-- **`polling-test-results`** — obtains the failure payload that feeds into this skill.
-- **`creating-fix-work-item`** — use to create a tracked fix item from the analysis output or to track an approved improvement suggestion as a work item once the user decides to act on it.

package/skills/configuring-quality-gate/SKILL.md

@@ -1,120 +0,0 @@
----
-name: configuring-quality-gate
-description: "Creates a DevOps Center quality gate with associated rules (PASS_PERCENTAGE, SEVERITY, ESSENTIAL) and links it to a pipeline-stage suite assignment, after showing a mandatory impact preview and obtaining explicit confirmation. Use this skill when a user wants to set or configure a quality gate, change a coverage threshold, or establish testing benchmarks on a pipeline stage. TRIGGER when: the user wants to set/configure a quality gate, change a coverage threshold, or set testing benchmarks on a stage. DO NOT TRIGGER when: only re-running an existing gate (use running-devops-test-suite in retrigger mode)."
-metadata:
-  version: "1.0"
-  minApiVersion: "67.0"
----
-
-## Prerequisites
-
-Load `checking-devops-prerequisites` first — Prerequisites 1–4 AND Prerequisite 5 (stage). You need `doce-org-alias`, `pipelineId`, `stageId`, and the target `DevopsTestSuiteStage` record Id.
-
-## Inputs required
-
-| Input | Source |
-|---|---|
-| `name` | User-provided name for the quality gate |
-| `rules` | List of `{type, threshold?}` — see rule types below |
-| `doce-org-alias` | Established in Prereq 1 |
-| `testSuiteStageId` | Target `DevopsTestSuiteStage` record Id (Prereq 5) |
-
-## Rule types
-
-| Type | Description | Threshold |
-|---|---|---|
-| `PASS_PERCENTAGE` | Minimum % of tests that must pass | Required (0–100) |
-| `SEVERITY` | Maximum allowed severity level of failures | Required (numeric, e.g. 1–5) |
-| `ESSENTIAL` | All essential tests must pass | Not required |
-
----
-
-## MANDATORY IMPACT PREVIEW
-
-**Before executing any commands**, show the user this preview and wait for explicit confirmation:
-
-> "Here's what this quality gate will enforce on `<stageName>`:
-> - Rule: `<type>` — `<description>`
-> - Threshold: `<value>`
-> - Affected pipelines: `<list>`
->
-> Confirm to apply?"
-
-**Never proceed past this point without showing the impact preview first and receiving explicit confirmation.**
-
----
-
-## Confirmation gate
-
-Only proceed with the steps below after the user has explicitly confirmed (e.g., "yes", "confirm", "go ahead"). If the user declines or does not confirm, stop and do not execute any commands.
-
----
-
-## Step 1 — Create the gate record
-
-```bash
-sf api request rest \
-  "/services/data/v67.0/connect/devopstesting/qualityGate" \
-  --method POST \
-  --body '{"name": "<gateName>"}' \
-  --target-org <doce-org-alias>
-```
-
-Extract `qualityGateId` from the response.
-
-## Step 2 — Create each rule as a sObject record
-
-Rules are not accepted in the Connect API payload — create them as `DevopsQualityGateRule` records directly. Only create rules the user has requested. `ESSENTIAL` has no threshold.
-
-```bash
-sf data create record \
-  --sobject DevopsQualityGateRule \
-  --values "DevopsQualityGateId='<qualityGateId>' Rule='PASS_PERCENTAGE' Threshold=<value>" \
-  --target-org <doce-org-alias> --json
-
-sf data create record \
-  --sobject DevopsQualityGateRule \
-  --values "DevopsQualityGateId='<qualityGateId>' Rule='ESSENTIAL'" \
-  --target-org <doce-org-alias> --json
-
-sf data create record \
-  --sobject DevopsQualityGateRule \
-  --values "DevopsQualityGateId='<qualityGateId>' Rule='SEVERITY' Threshold=<value>" \
-  --target-org <doce-org-alias> --json
-```
-
-## Step 3 — Link the gate to the suite stage
-
-Update the `DevopsTestSuiteStage` record to link the new gate:
-
-```bash
-sf data update record \
-  --sobject DevopsTestSuiteStage \
-  --record-id <testSuiteStageId> \
-  --values "IsQualityGateEnabled=true DevopsQualityGateId='<qualityGateId>'" \
-  --target-org <doce-org-alias> --json
-```
-
----
-
-## On success
-
-Confirm to the user:
-> "Quality gate `<gateName>` created with `<N>` rule(s) and assigned to `<suiteName>` on `<stageName>`."
-
-## Error handling
-
-Never expose raw API errors. Use the following responses:
-
-| Status | Response |
-|---|---|
-| 400 | "The quality gate configuration is invalid. Check that all rule types and thresholds are correct." |
-| 403 | "You don't have permission to configure quality gates on this org." |
-| 500 | "A server error occurred. Try again in a few minutes." |
-
----
-
-## Related skills
-
-- To re-run a gate after meeting threshold, use `running-devops-test-suite` (retrigger mode).
-- To assign or map suites to stages, use `managing-suite-assignments`.

package/skills/configuring-test-provider/SKILL.md

@@ -1,113 +0,0 @@
----
-name: configuring-test-provider
-description: "Configures an available test provider (e.g. Apex Unit Tests, Code Analyzer, Flow Tests, Provar) on a DevOps Center pipeline via the Connect API, after explicit user confirmation, so the provider's test suites become available for assignment to pipeline stages. Takes a pipelineId and a testProviderId. Use this skill when a provider is available on the pipeline but not yet configured and the user wants to enable it. TRIGGER when: the user wants to configure, enable, set up, or add a test provider on a pipeline, or wants a not-yet-configured provider's suites to become available. DO NOT TRIGGER when: re-syncing an already-configured provider to pick up new suites (use syncing-test-providers), or assigning existing suites to a stage (use managing-suite-assignments)."
-metadata:
-  version: "1.0"
-  minApiVersion: "67.0"
----
-
-# Configuring a Test Provider
-
-Configures an available test provider on a DevOps Center pipeline, making its test suites available for assignment to pipeline stages.
-
-**Confirmation required:** Yes — explicit confirmation before the provider is configured.
-
-## Prerequisites
-
-Load `checking-devops-prerequisites` first — Prerequisites 1–4 (org login, Agentforce DX plugin, DevOps Center org auth, pipeline identified). Prerequisite 5 (stage) is **not** required: providers are configured at the pipeline level, not the stage level.
-
-| Variable | Source |
-|---|---|
-| `doce-org-alias` | Established in Prerequisite 1 |
-| `pipelineId` | Identified in Prerequisite 4 (pipeline selection) |
-| `testProviderId` | Resolved by fetching the pipeline's test providers (below) |
-
----
-
-## Step 1 — Fetch test providers to resolve the provider ID
-
-Get all test providers for the pipeline so you can resolve the `testProviderId` and confirm which providers are still available to configure:
-
-```bash
-sf api request rest \
-  "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/testProviders?status=all" \
-  --target-org <doce-org-alias>
-```
-
-Each provider entry includes `testProviderId`, `testProviderName`, and a status (Configured vs. Available). Present a short summary grouped by status:
-
-```text
-Test providers for <pipelineName>:
-
-✓ Configured:
-- Code Analyzer (63 suites)
-- Apex Unit Tests (5 suites)
-
-Available (not yet configured):
-- Flow Tests
-```
-
-- **Only an Available provider can be configured.** If the pipeline has no available providers, report that and stop — do NOT fabricate a provider or ID.
-
-### If the named provider is already Configured
-
-Do **not** present the confirmation gate and do **not** POST to the configure endpoint (Steps 2–3) — that would create a duplicate `DevopsPipelineTestProvider`. Instead:
-
-1. State plainly that the provider is already configured, including its synced suite count and last-sync time if returned (e.g. *"Flow Tests is already configured on `<pipelineName>` with 3 suites synced (last sync 2026-06-23)."*).
-2. Diagnose the user's actual goal and redirect **by name**:
-   - If the user says the provider's **suites don't appear when assigning tests to a stage**, this is a **stage-assignment gap, not a provider-configuration gap** — the suites already exist at the pipeline level; they just need to be linked to the stage. Redirect to **`managing-suite-assignments`**.
-   - If the user expects **newly created suites** that aren't yet synced, redirect to **`syncing-test-providers`** (re-sync via `POST /connect/devops/sync`) to pull them in.
-3. Do not loop back to configuring — finish cleanly after the explanation and redirect.
-
-## Step 2 — Confirmation gate
-
-**Required — do not call the API before the user confirms.**
-
-> "I'll configure `<testProviderName>` on the `<pipelineName>` pipeline. This will make its suites available for assignment to stages. Confirm?"
-
-Do not proceed until the user gives an affirmative response.
-
-## Step 3 — Configure the provider
-
-On confirmation, call the configure endpoint with the provider ID:
-
-```bash
-sf api request rest \
-  "/services/data/v67.0/connect/devops/pipeline/<pipelineId>/testProvider" \
-  --method POST \
-  --body '{"testProviderId": "<testProviderId>"}' \
-  --target-org <doce-org-alias>
-```
-
-## On success
-
-> "Provider `<testProviderName>` is now configured on the `<pipelineName>` pipeline. Its suites are available for assignment to stages."
-
-Newly configured suites can then be assigned to stages with `managing-suite-assignments`.
-
----
-
-## Critical gotcha
-
-This `POST .../pipeline/<pipelineId>/testProvider` endpoint **creates a new provider configuration record** (`DevopsPipelineTestProvider`). Use it ONLY to configure a provider for the first time. To re-sync an already-configured provider for new suites, use `syncing-test-providers` (`POST /connect/devops/sync`) — calling this configure endpoint on an already-configured provider produces **duplicate** `DevopsPipelineTestProvider` records.
-
-## Error Handling
-
-Never expose raw API error messages, stack traces, or JSON payloads to the user. Map response status codes to plain-language messages:
-
-| Status | User-facing message |
-|---|---|
-| 400 | "The request was invalid. Check that the provider ID and pipeline ID are correct." |
-| 403 | "You don't have permission to configure test providers on this pipeline." |
-| 404 | "The pipeline or test provider was not found." |
-| 409 | "That provider appears to already be configured on this pipeline. To pick up new suites, re-sync it instead." |
-| 500 | "A server error occurred. Try again in a few minutes." |
-
----
-
-## Related skills
-
-- **`checking-devops-prerequisites`** — loaded first to establish org and pipeline context.
-- **`syncing-test-providers`** — once a provider is configured, use this to re-sync it later and pull in newly added suites.
-- **`managing-suite-assignments`** — after configuring a provider, use this to assign or map its suites to a pipeline stage.
-- **`recommending-devops-tests`** — to recommend which of the newly available suites to run.