@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/agentforce-generate/references/agent-audit-scope-path-review.md

@@ -0,0 +1,180 @@
+# AgentScript Audit Scope and Path Review
+
+Follow this first half of the audit workflow before selecting or applying a
+repair level.
+
+## Contents
+
+- [Establish Scope and Evidence](#1-establish-scope-and-evidence)
+- [Reconstruct the Use Cases](#2-reconstruct-the-use-cases)
+- [Audit Every Reachable Path](#3-audit-every-reachable-path)
+
+## Workflow
+
+### 1. Establish Scope and Evidence
+
+- Locate the complete `.agent` bundle, its metadata, action implementations,
+  Agent Spec, test specifications, and relevant repository instructions.
+- Determine whether the input is a complete agent, one extracted subagent, or
+  a pasted fragment. Do not report missing bundle scaffolding as a defect in an
+  intentionally extracted fragment.
+- Inspect the worktree before editing. Preserve unrelated user changes.
+- Identify available validation surfaces: Salesforce CLI and target org,
+  project commands, preview, test suites, and session traces.
+- Read the full agent and every directly referenced action contract needed to
+  understand its behavior. Do not infer action outputs from names alone.
+- Create the audit ledger or report shell now. Record artifact scope, baseline
+  identity, evidence limits, initial use cases, and the highest-priority
+  supported observations. Keep incomplete entries explicitly marked instead of
+  withholding the artifact until the audit is complete.
+- Run the strongest available read-only project check. If an authenticated
+  target org and complete bundle are available, run:
+
+  ```bash
+  sf agent validate authoring-bundle --json --api-name <BundleName>
+  ```
+
+  Preserve the baseline diagnostics.
+
+If only a fragment is available, perform a bounded semantic review and state
+which structural, reachability, and runtime claims cannot be verified.
+
+#### Scale the audit before reading a large agent
+
+As a workflow heuristic, use the indexed audit below when a file is large
+enough that a single-pass review would lose cross-node context. Rough defaults
+are more than 2,000 lines or 10 execution nodes; adjust them to the density and
+complexity of the artifact. They are not AgentScript runtime limits.
+
+1. Build a deterministic index first: block boundaries, variables, actions,
+   action outputs, transitions, lifecycle hooks, and available diagnostics.
+   Follow [AgentScript Compiler Setup](agentscript-toolchain.md) to load an
+   ambient SDK, install the public npm package, or build the public source
+   fallback, then run
+   `node <skill-directory>/scripts/index-agent.mjs <path-to-agent-file>` and
+   retain its JSON outside the bundle. This helper uses the real
+   parser/compiler rather than regex and reports its exact provider. If both
+   installation paths fail, record **compiler not used** and continue with
+   target-org validation or a bounded static review; do not stall the audit.
+2. Seed one audit ledger keyed by execution node and use-case ID immediately
+   after indexing. Do not rely on a single giant narrative summary.
+3. Screen each node for user-visible harm and confidence. Add supported
+   Critical and High findings to the ranked ledger as soon as they are found;
+   do not wait for every node to be deeply traced.
+4. Deep-trace the highest-ranked affected paths first. Open another reference
+   or source file only after naming the decision its evidence could change.
+   Stop a line of inquiry when two consecutive reads or queries add no material
+   evidence to that decision.
+5. Checkpoint the ledger after each reviewed node or coherent cause group. Mark
+   remaining nodes as pending so an interrupted audit still leaves a useful,
+   honest deliverable.
+6. After the node screening pass, run one cross-node pass for shared variables,
+   instruction overrides, transition arrivals, action ownership, and reset
+   behavior, then revise the rankings.
+7. Repair one coherent cause group per batch. Keep a coupled group small enough
+   to attribute any regression, then run validation, affected regression cases,
+   and representative unaffected canaries before the next batch.
+8. Report deferred accepted findings after every batch. Do not hold the first
+   useful result until the whole file has been rewritten.
+
+Large size is not itself a defect. Do not split an agent merely to make the
+analysis easier.
+
+### 2. Reconstruct the Use Cases
+
+Build a use-case matrix before fixing anything. Prefer, in order:
+
+1. user-supplied behavior and acceptance criteria;
+2. an approved Agent Spec;
+3. existing tests and evaluation definitions;
+4. reachable behavior inferred from the agent and action contracts.
+
+Label inferred use cases. Do not quietly turn them into new requirements.
+
+For each user-facing objective, record:
+
+- initial utterance and required follow-up turns;
+- expected response, question, action, transition, refusal, or escalation;
+- actions that must be available and actions that must be unavailable;
+- trusted prerequisites and expected state changes;
+- external side effect, if any, and which mechanism owns it.
+
+Include only the boundaries material to the artifact or user intent:
+
+- positive path;
+- missing or invalid input;
+- failure and retry;
+- cancellation or topic switch when supported;
+- repeated request or repeated action;
+- multi-turn continuation;
+- transition arrival with the current customer message;
+- explicit negative action-availability cases.
+
+### 3. Audit Every Reachable Path
+
+Trace each use case through:
+
+```text
+effective instructions
+-> available actions
+-> selected action or response
+-> returned output
+-> stored state
+-> next reasoning iteration or transition
+-> externally observable result
+```
+
+Apply every relevant category in the Diagnostic Catalog. Pay special attention
+to:
+
+- structural indentation versus indentation inside `|` text;
+- repeated adjacent `|` markers that fragment one contiguous prompt block;
+- runtime values named in `|` text without `{!@variables.X}` interpolation;
+- exact machine-known comparisons whose consequences must be stable but are
+  written as model prose instead of runtime predicates;
+- subagent system instructions replacing global instructions;
+- independent conditions that overlap or leave gaps;
+- invalid `elif`, unsupported nested conditionals, or independent branches that
+  should be one first-match `else if` chain;
+- HyperClassifier used for a node that must do more than transition, or omitted
+  from a compatible pure router despite an established routing-latency need;
+- action availability broader than the prompt branch mentioning it;
+- `|` prompt text treated as though it pauses deterministic `run`, `set`, or
+  `if` resolution;
+- a requested model action treated as executed merely because the model was
+  told to call it;
+- raw or stale outputs controlling consequential decisions;
+- completion flags set before every derived field is usable;
+- redundant state that encodes one phase several ways, duplicates conversation
+  history, or lacks reset semantics;
+- reasoning burden that exceeds the target model's demonstrated capability;
+- lifecycle hooks that overwrite legitimate later state;
+- unsupported syntax or lifecycle constructs;
+- two mechanisms claiming the same side effect;
+- tests that encode a new preference instead of existing intent.
+- categorical or causal findings whose evidence supports only a recommendation,
+  possibility, or version-specific observation.
+
+Rank findings by observable harm, not visual ugliness:
+
+- **Critical:** unsafe or unauthorized effect, data exposure, or systemic
+  inability to perform the primary objective.
+- **High:** wrong routing, wrong action, duplicate effect, dead primary path,
+  or trusted decision based on untrusted data.
+- **Medium:** reachable failure, retry, continuation, or maintenance defect
+  with bounded impact.
+- **Low:** concrete clarity or resilience defect with a plausible failure mode.
+
+No location, consequence, use case, and verification plan means no finding.
+A missing entry in an abbreviated reference list is not evidence of a defect.
+Likewise, a style preference with no diagnostic, supported-use-case
+consequence, or user-approved cleanup scope is not a Surface repair. Preserve
+valid optional metadata and semantically equivalent control-flow shapes.
+Do not add a supposedly required field to an existing bundle without a
+diagnostic from the selected compiler or target validator and evidence for its
+correct value. Never guess deployment semantics merely to complete a schema.
+
+Keep the ranked ledger current while tracing. Finish the Critical and High
+paths before spending time on Medium or Low hypotheses. A lower-priority issue
+may be recorded as pending when further research would delay a supported,
+higher-impact finding or repair.

package/skills/agentforce-generate/references/agent-design-and-spec-creation.md

@@ -22,6 +22,10 @@ when the runtime needs it. Build the spec before writing Agent Script. For
 existing agents, reverse-engineer the spec from the `.agent` file so intent is
 explicit before changes.
 
+If the user supplies a sufficiently detailed design or Agent Spec and explicitly
+says it is already approved, use it as the current build contract. Do not
+recreate or reapprove it unless requirements are missing or materially change.
+
 ### What an Agent Spec Contains
 
 - **Purpose & Scope** — what business outcome the agent should drive
@@ -229,19 +233,22 @@ subagent off_topic:
     description: "Handle off-topic requests"
     reasoning:
         instructions: ->
-            | You asked about something outside my scope.
-              I can only help with [list your capabilities].
-              What can I help you with today?
+            | Explain that the request is outside scope, state the supported
+              capabilities, and ask which supported task the user wants help
+              with.
 
 subagent ambiguous_question:
     description: "Ask for clarification"
     reasoning:
         instructions: ->
-            | I didn't quite understand your request.
-              Can you provide more details about what you need?
+            | Explain briefly that the request is unclear and ask one focused
+              question for the missing detail needed to proceed.
 ```
 
-**Escalation Subagents.** Hand off to a human via `@utils.escalate`. This is a permanent exit — the user leaves the agent for a support channel (phone, email, chat with a human). Once triggered, the agent session ends. The escalation action does NOT return.
+**Escalation Subagents.** Hand off via `@utils.escalate`. It ends the current
+agent turn and transfers control to the configured escalation path; the source
+subagent does not resume automatically. Do not assume the broader messaging
+session ends unless that channel's escalation contract says so.
 
 ```agentscript
 subagent escalation:
@@ -307,11 +314,18 @@ subagent local_events:
 # resort_hours, off_topic, ambiguous_question defined further down the file
 ```
 
-**Externally Ordered Flow.** Subagents may form a pipeline when an external
-protocol requires successful step 1 before step 2 (for example, verified
-identity before a protected commit). Do not turn an ordinary multi-question
-conversation into a pipeline. Every locked stage needs correction,
-cancellation, and intent-change behavior.
+**Staged Flow.** Subagents may form a pipeline when the benefit of strict
+ordering outweighs the loss of conversational flexibility—for example, when
+an external protocol requires successful verification before a protected
+commit. A staged flow improves repeatability and auditability, but adds state,
+maintenance, and friction around corrections or changed intent. A prompt-led
+multi-question conversation is usually more flexible but cannot guarantee the
+same order.
+
+Choose deliberately. For stages that persist across turns, define the
+correction, cancellation, retry, or intent-change behavior that the actual use
+cases need. A short-lived deterministic guard does not need ceremonial state
+or every possible exit path.
 
 ```agentscript
 start_agent intake:
@@ -439,25 +453,16 @@ public class WeatherFetcher {
 }
 ```
 
-Wire with: `target: "apex://ClassName"`
-
-> **One `@InvocableMethod` per Apex class — one class per action.** Salesforce permits **only one** `@InvocableMethod` in a given Apex class. The `apex://` target therefore names the **class**, not a method: use `apex://ClassName` — never `apex://ClassName.methodName`. Each distinct Apex-backed action MUST point at its **own** class.
->
-> A common mistake is to treat one Apex class as a namespace for several related actions:
-> ```agentscript
-> # WRONG — 5 actions sharing one class (won't compile: >1 @InvocableMethod per class)
-> target: "apex://CaseIntelligence.searchSimilarCases"
-> target: "apex://CaseIntelligence.summarizeResolution"
-> target: "apex://CaseIntelligence.proposeResolution"
-> ```
-> The `ClassName.method` shape *looks* like ordinary OOP and invites treating one class as a home for several actions. The **verified** failure mode is the shared class: a single `CaseIntelligence` class carrying multiple `@InvocableMethod`s fails Apex compilation with `Only one method per type can be defined with: InvocableMethod`, which cascades into failed deploy, failed publish, and no grounded action calls at runtime (observed in the `enterprise-use-cases` eval run). Whether the `.method` **suffix in the target string itself** breaks resolution or is simply ignored by the runtime is not independently confirmed here — but authoring it invites the shared-class pattern above, so treat `apex://ClassName` (no suffix) as the rule.
-> ```agentscript
-> # RIGHT — one class per action, distinct class names, no method suffix
-> target: "apex://CaseIntelligenceSearchSimilarCases"
-> target: "apex://CaseIntelligenceSummarizeResolution"
-> target: "apex://CaseIntelligenceProposeResolution"
-> ```
-> When several actions are conceptually related, give each its own class with a shared prefix (e.g. `CaseIntelligence…`) rather than sharing one class. Never emit two `apex://` targets that resolve to the same class name.
+Wire with the exact registered target identifier, commonly
+`target: "apex://ClassName"`.
+
+> **One `@InvocableMethod` per Apex class.** This verified Apex constraint
+> governs implementation structure; it does not justify rewriting an action
+> target supplied by the user, project, org metadata, or an approved contract.
+> Preserve the exact target. If its implementation mapping is uncertain, flag
+> that uncertainty and verify it from the implementation or target org before
+> proposing a contract change. Do not infer from a dotted target that several
+> `@InvocableMethod`s share one class.
 
 **Flows**: Only **autolaunched Flows** work. Screen Flows, record-triggered Flows, and schedule-triggered Flows will not work. The Flow must start only when explicitly invoked.
 
@@ -740,7 +745,7 @@ ALWAYS fix deploy errors BEFORE generating and deploying the next stub.
 
 When creating a new agent, label every transition in your Agent Spec's Subagent Map as either **handoff** or **delegation**. When analyzing an existing agent, classify each transition to determine whether context flow matches the design intent.
 
-### Handoff: Permanent Transition
+### Handoff: Non-Returning Transition
 
 A handoff is a one-way transition. The user moves to a new subagent and control never returns to the original subagent. Handoffs use `@utils.transition to` in `reasoning.actions`.
 
@@ -840,54 +845,82 @@ subagent admin_panel:
               If they are not an admin, tell them access is denied.
 ```
 
-The LLM may comply, or it may not — instructions are suggestions. The RIGHT approach uses a `before_reasoning` guard that the runtime enforces before the LLM is ever invoked. See Section 8 for all gating mechanisms.
+Model instructions influence behavior but do not provide the same enforcement
+as a runtime gate over a trusted authorization value. For this protected
+boundary, use a `before_reasoning` guard that resolves before the planner. See
+Section 8 for the available gating mechanisms.
 
 ### Writing Effective Instructions
 
-Two factors govern subjective control effectiveness: instruction ordering and grounding.
-
-**Instruction Ordering.** The runtime resolves instructions top-to-bottom — evaluating `if/else` blocks and expanding template expressions — before the LLM sees the result. The resolved text becomes the LLM's prompt. Put post-action checks first, data references next, dynamic conditional text last.
+Three useful factors for subjective control effectiveness are clear response
+duties, instruction ordering, and grounding.
+
+**Describe the duty, not a draft reply.** By default, tell the model what the
+response must accomplish: the facts to use, claims to avoid, action to take,
+and next conversational objective. Do not write ordinary prompt fragments as
+finished user-facing copy. Copy-first instructions can hide the intended
+behavior, adapt poorly to conversation context, and make conflicting duties
+harder to notice.
+
+Use exact response copy only when the wording itself is a requirement, such as
+an approved legal or compliance notice. State that contract explicitly with
+language such as `Respond with exactly this text, with no additions:`. Label
+optional wording as an example and state which tone or content properties the
+model should preserve.
+
+**Instruction Ordering.** The runtime resolves instructions top-to-bottom —
+evaluating conditions and expanding template expressions — before the LLM sees
+the assembled result. Ordering controls the order of prompt fragments, not
+whether the model can respond before a later deterministic condition resolves.
+Put the current objective and highest-consequence guidance where it is easy to
+notice, and use exclusive predicates or a transition when two duties must not
+coexist.
 
 The checkout examples assume `cart_validation_failed`, `cart_total`,
 `free_shipping_eligible`, and `shipping_cost` are exact outputs from cart and
 entitlement actions. Each is consumed by the shown prompt branch or output
 reference; none mirrors a conversational fact.
 
-RIGHT: Post-action check at the top (LLM sees it first)
+RIGHT: Completed and first-entry duties are mutually exclusive
 ```agentscript
 subagent checkout:
     reasoning:
         instructions: ->
-            # Post-action check — LLM sees this first
             if @variables.cart_validation_failed:
-                | Your cart has items that are no longer available.
-                  Please remove them and try again.
+                | Explain that one or more cart items are unavailable. Do not
+                  offer payment. Ask the user to review or remove those items.
 
-            # Data reference — LLM sees the resolved value
-            | Your current cart total is {!@variables.cart_total}.
+            if @variables.cart_validation_failed == False:
+                | Tell the user the current cart total is
+                  {!@variables.cart_total}. Ask whether they want to proceed to
+                  payment or cancel.
 
-            # Dynamic instructions — conditional on state
-            if @variables.free_shipping_eligible:
-                | You qualify for FREE shipping.
-            else:
-                | Standard shipping is {!@variables.shipping_cost}.
+            if @variables.cart_validation_failed == False and @variables.free_shipping_eligible:
+                | Tell the user shipping is free.
 
-            | Proceed to payment or cancel?
+            if @variables.cart_validation_failed == False and @variables.free_shipping_eligible == False:
+                | Tell the user standard shipping costs
+                  {!@variables.shipping_cost}.
 ```
 
-WRONG: Post-action check at the bottom (LLM may respond before seeing it)
+WRONG: Conflicting fragments can be assembled together
 ```agentscript
 subagent checkout:
     reasoning:
         instructions: ->
-            | Your current cart total is {!@variables.cart_total}.
-              Proceed to payment or cancel?
+            | Tell the user the current cart total is
+              {!@variables.cart_total}. Ask whether they want to proceed to
+              payment or cancel.
 
-            # Too late — LLM may already be generating a response
             if @variables.cart_validation_failed:
-                | Your cart has items that are no longer available.
+                | Explain that one or more cart items are unavailable and ask
+                  the user to review or remove them.
 ```
 
+The problem is not that the model responds before the bottom condition is
+evaluated; deterministic resolution finishes first. The problem is that both
+the payment duty and failure duty can reach the same assembled prompt.
+
 **Grounding.** The platform's grounding service validates that the agent's response matches action output data. Paraphrasing or embellishing may cause grounding failures. In the example below, `event_date` is exact action output consumed by the response.
 
 - Use specific values: `"The event is on {!@variables.event_date}"` grounds reliably; `"The event is next week"` may not.
@@ -896,11 +929,20 @@ subagent checkout:
 
 Grounding validation requires **live mode preview** (`sf agent preview --use-live-actions --json`). Simulated mode preview generates fake outputs, so grounding has nothing real to validate against.
 
-**Naming output fields in post-action instructions.** ALWAYS specify which output fields to include in text responses. Generic instructions like "present the results clearly" let platform-injected tools hijack the response. EXAMPLE: The LLM calls `show_command` instead of composing text, producing generic "Here are the results:" message wrapper with raw structured data. This can corrupt session state, causing subsequent turns to fail with generic "something went wrong" message. Naming output fields steers the LLM toward composing a direct text response. This reliably grounds the response because it maps closely to action output values. ALWAYS include `Do NOT use the show_command tool. Always compose your response as direct text.` in post-action instructions. See *Anti-Patterns* in the *Core Language* reference for full WRONG/RIGHT example.
+**Naming output fields in post-action instructions.** Name the fields needed in
+the response when generic result-presentation guidance produces the wrong
+format or tool choice in the target runtime. Observed configurations may expose
+platform presentation tools such as `show_command`; if traces show the model
+selecting one when direct text is required, add a scoped instruction to compose
+text and test it with that configuration. Do not add a universal
+`show_command` prohibition to agents where the tool is absent or desired.
 
 ### Post-Action Behavior
 
-When an action completes without triggering a transition, the subagent stays active. The runtime re-evaluates the entire subagent — resolving instructions top-to-bottom again with updated variables, then passing the new prompt to the LLM. The LLM may call the same action again. To prevent unwanted loops, see Section 9 (Action Loop Prevention).
+When a model-selected action batch completes without a handoff, pause,
+cancellation, or limit, the runtime begins another reasoning iteration with
+updated state. The LLM may call the same still-available action again. To
+prevent unwanted loops, see Section 9 (Action Loop Prevention).
 
 ---
 
@@ -1003,10 +1045,13 @@ subagent checkout:
 
     reasoning:
         instructions: ->
-            | Review your order.
-
             if @variables.items_in_cart == 0:
-                | Your cart is empty. Go back and select items.
+                | Explain that the cart is empty and ask the user to select an
+                  item before checkout.
+
+            if @variables.items_in_cart > 0:
+                | Summarize the current order and help the user review it before
+                  payment.
 
         actions:
             pay: @actions.process_payment
@@ -1042,8 +1087,9 @@ subagent verification:
 ```
 
 Each flag has one trusted writer and a named next-step consumer. Failed actions
-must leave the next action unavailable. Define correction, cancellation, reset,
-and expiry semantics for the real workflow.
+must leave the next action unavailable. Define only the correction,
+cancellation, reset, and expiry semantics relevant to the real workflow and
+the lifetime of that state.
 
 ### Same-Turn Behavior After Gate Transitions