Deprecate needs.activation.outputs.* in workflow markdown; update all docs to use steps.sanitized.outputs.* (#21682)

Author: Copilot

.github/aw/create-agentic-workflow.md

@@ -539,7 +539,7 @@ These resources contain workflow patterns, best practices, safe outputs, and per
      - Prefer `safe-outputs` (`create-issue`, `add-comment`, `create-pull-request`, `create-pull-request-review-comment`, `update-issue` for editing, `close-issue` for closing, `dispatch-workflow`) over granting write perms.
      - For custom write operations to external services (email, Slack, webhooks), use `safe-outputs.jobs:` to create custom safe output jobs.
      - Constrain `network:` to the minimum required ecosystems/domains.
-     - Use sanitized expressions (`${{ needs.activation.outputs.text }}`) instead of raw event text.
+     - Use sanitized expressions (`${{ steps.sanitized.outputs.text }}`) instead of raw event text.
    - **Emphasize human agency in workflow prompts**:
      - When writing prompts that report on repository activity (commits, PRs, issues), always attribute bot activity to humans
      - **@github-actions[bot]** and **@Copilot** are tools triggered by humans - workflows should identify who triggered, reviewed, or merged their actions
@@ -571,14 +571,14 @@ safe-outputs:
 # Deploy Preview
 
 Deploy a preview environment for this pull request. The caller wrote:
-"${{ needs.activation.outputs.text }}"
+"${{ steps.sanitized.outputs.text }}"
 ```
 
 **Tradeoffs:**
 - ✅ Works across issues, PRs, and all comment types (configurable via `events:`)
 - ✅ Natural to invoke — users type `/command` in any comment
 - ✅ Supports multiple command aliases in one workflow (`name: ["deploy", "redeploy"]`)
-- ✅ The triggering comment text is available as context via `needs.activation.outputs.text`
+- ✅ The triggering comment text is available as context via `steps.sanitized.outputs.text`
 - ⚠️ Less discoverable — users must know the command name exists
 - ⚠️ Cannot be triggered without writing a comment (no label-based invocation)
 

.github/aw/github-agentic-workflows.md

@@ -273,7 +273,7 @@ When updating workflows, maintain security:
 - Default to `permissions: read-all` and expand only if necessary
 - Prefer `safe-outputs` over granting write permissions
 - Constrain `network:` to the minimum required ecosystems/domains
-- Use sanitized expressions (`${{ needs.activation.outputs.text }}`)
+- Use sanitized expressions (`${{ steps.sanitized.outputs.text }}`)
 
 ## Update Workflow Process
 

.github/aw/update-agentic-workflow.md

@@ -47,7 +47,7 @@ on:
     types: [opened]
 ---
 
-# Analyze issue: "${{ needs.activation.outputs.text }}"
+# Analyze issue: "${{ steps.sanitized.outputs.text }}"
 ```
 
 **Benefits**:
@@ -95,7 +95,7 @@ tools:
 ```markdown
 Repository: ${{ github.repository }}
 Issue Number: ${{ github.event.issue.number }}
-Issue Content: "${{ needs.activation.outputs.text }}"
+Issue Content: "${{ steps.sanitized.outputs.text }}"
 
 Analyze the above issue (content already provided).
 ```
@@ -158,7 +158,7 @@ on: issues
 
 # Issue Triage for #${{ github.event.issue.number }}
 
-**Issue Content**: "${{ needs.activation.outputs.text }}"
+**Issue Content**: "${{ steps.sanitized.outputs.text }}"
 
 Tasks:
 1. Categorize issue type (bug/feature/question)
@@ -352,11 +352,11 @@ Annual cost (500 runs): ~$75
 Get the full issue details, then summarize the description.
 ```
 
-**Problem**: Fetches large response just to extract what's already in `needs.activation.outputs.text`.
+**Problem**: Fetches large response just to extract what's already in `steps.sanitized.outputs.text`.
 
 **Solution**:
 ```markdown
-Issue: "${{ needs.activation.outputs.text }}"
+Issue: "${{ steps.sanitized.outputs.text }}"
 Summarize the above issue content.
 ```
 
@@ -409,7 +409,7 @@ grep -A5 "token_usage" logs/*.log
 ```
 
 **Solution**:
-1. Replace API calls with `needs.activation.outputs.text`
+1. Replace API calls with `steps.sanitized.outputs.text`
 2. Reduce tool permissions to minimum
 3. Add explicit "don't re-fetch" instructions
 
@@ -446,4 +446,4 @@ grep "turn" logs/*.log | wc -l
 - Issue #1728: Token usage optimization case study (481k → 150k)
 - Issue #2012: Workflow performance analysis patterns
 - `gh aw logs` documentation: Analyzing workflow execution
-- Sanitized context text: Using `needs.activation.outputs.text`
+- Sanitized context text: Using `steps.sanitized.outputs.text`

.github/copilot/instructions/workflow-performance.md

@@ -772,40 +772,35 @@ go test -race ./...
 
 ### Expression Transformations in Workflows
 
-**Automatic Activation Output Transformations:**
+**Deprecated: `needs.activation.outputs.*` in Workflow Markdown**
 
-The compiler automatically transforms certain `needs.activation.outputs.*` expressions to `steps.sanitized.outputs.*` for compatibility with the activation job context.
+Use `steps.sanitized.outputs.text/title/body` directly in workflow markdown prompts:
 
-**Why this transformation occurs:**
+- `${{ steps.sanitized.outputs.text }}` — sanitized full context
+- `${{ steps.sanitized.outputs.title }}` — sanitized issue/PR title
+- `${{ steps.sanitized.outputs.body }}` — sanitized issue/PR body
 
-The prompt is generated **within the activation job**, which means it cannot reference its own `needs.activation.*` outputs (a job cannot reference its own needs outputs in GitHub Actions). The compiler automatically rewrites these expressions to reference the `sanitized` step, which computes sanitized versions of the triggering content.
+**Why the `steps.sanitized.*` form is required:**
 
-**Transformations:**
+The prompt is generated **within the activation job**, which means it cannot reference its own `needs.activation.*` outputs (a job cannot reference its own needs outputs in GitHub Actions). The `sanitized` step within the activation job computes sanitized versions of the triggering content.
+
+**Backward compatibility:**
+
+The compiler still accepts the old form (`needs.activation.outputs.text/title/body`) and automatically rewrites it to `steps.sanitized.outputs.*`, but emits a deprecation warning. Use `steps.sanitized.outputs.*` directly in all new and updated workflows.
+
+**Old deprecated form → new correct form:**
 - `needs.activation.outputs.text` → `steps.sanitized.outputs.text`
 - `needs.activation.outputs.title` → `steps.sanitized.outputs.title`
 - `needs.activation.outputs.body` → `steps.sanitized.outputs.body`
 
 **Important notes:**
-- Only `text`, `title`, and `body` outputs are transformed
-- Other activation outputs (`comment_id`, `comment_repo`, `slash_command`) are NOT transformed
-- Transformation uses word boundary checking to prevent incorrect partial matches (e.g., `text_custom` is not transformed)
-- This is particularly important for runtime-import, where markdown can change without recompilation
-
-**Example:**
-
-```markdown
-Analyze this content: "${{ needs.activation.outputs.text }}"
-```
-
-Is automatically transformed to:
-
-```markdown
-Analyze this content: "${{ steps.sanitized.outputs.text }}"
-```
+- Only `text`, `title`, and `body` outputs are affected; use `needs.activation.outputs.*` for `comment_id`, `comment_repo`, `slash_command` etc. in _downstream_ jobs
+- Backward-compat transformation uses word boundary checking (e.g., `text_custom` is not transformed)
 
 **Implementation:**
 - Transformation happens in `pkg/workflow/expression_extraction.go::transformActivationOutputs()`
 - Applied during expression extraction from markdown
+- Deprecation warnings emitted to stderr during compilation
 - Transformations are logged for debugging when `DEBUG=workflow:expression_extraction`
 
 ### YAML Library Usage

AGENTS.md

@@ -345,7 +345,7 @@ safe-outputs:
 ---
 # RECOMMENDED: Use sanitized context
 Analyze this issue content (safely sanitized):
-"${{ needs.activation.outputs.text }}"
+"${{ steps.sanitized.outputs.text }}"
 
 Metadata:
 - Issue #${{ github.event.issue.number }}

docs/slides/index.md

@@ -45,7 +45,7 @@ tracking issue in the central tracker.
 
 **Original issue:** ${{ github.event.issue.html_url }}
 **Issue number:** ${{ github.event.issue.number }}
-**Content:** "${{ needs.activation.outputs.text }}"
+**Content:** "${{ steps.sanitized.outputs.text }}"
 
 Create tracking issue with link to original, component identifier, summary, suggested priority, and labels `from-component-alpha` and `tracking-issue`.
 ```
@@ -179,7 +179,7 @@ safe-outputs:
 Analyze new issues and create tracking issues in appropriate repositories.
 
 **Original issue:** ${{ github.event.issue.html_url }}
-**Content:** "${{ needs.activation.outputs.text }}"
+**Content:** "${{ steps.sanitized.outputs.text }}"
 
 Analyze issue severity and route to appropriate tracker: security issues to `myorg/security-tracker`, features to `myorg/feature-tracker`, bugs to `myorg/bug-tracker`, or infrastructure to `myorg/ops-tracker`. Include original link, triage reasoning, priority, affected components, and SLA targets.
 ```

docs/src/content/docs/examples/multi-repo/issue-tracking.md

@@ -156,7 +156,7 @@ Read issue #${{ github.event.issue.number }} in repository ${{ github.repository
 
 Issue title: "${{ github.event.issue.title }}"
 
-Use sanitized content: "${{ needs.activation.outputs.text }}"
+Use sanitized content: "${{ steps.sanitized.outputs.text }}"
 
 Actor: ${{ github.actor }}
 Repository: ${{ github.repository }}
@@ -173,7 +173,7 @@ Arbitrary expressions are blocked for security. This will fail at runtime:
 Run this command: ${{ github.event.comment.body }}
 ```
 
-Use `needs.activation.outputs.text` for sanitized user input instead.
+Use `steps.sanitized.outputs.text` for sanitized user input instead.
 
 ## Quick Reference
 

docs/src/content/docs/guides/editing-workflows.md

@@ -75,11 +75,11 @@ Customize access with the `roles:` configuration. Use `roles: [admin, maintainer
 
 ## Accessing Context Information
 
-Access sanitized event context through `needs.activation.outputs.text`:
+Access sanitized event context through `steps.sanitized.outputs.text`:
 
 ```aw wrap
 # Reference the sanitized text in your workflow:
-Analyze this content: "${{ needs.activation.outputs.text }}"
+Analyze this content: "${{ steps.sanitized.outputs.text }}"
 ```
 
 Sanitization filters unauthorized mentions, malicious links, and excessive content while preserving essential information.

docs/src/content/docs/patterns/chat-ops.md

@@ -42,10 +42,10 @@ safe-outputs:
 
 ## Accessing Issue Context
 
-Access sanitized issue content through `needs.activation.outputs.text`, which combines title and description while removing security risks (@mentions, URIs, injections):
+Access sanitized issue content through `steps.sanitized.outputs.text`, which combines title and description while removing security risks (@mentions, URIs, injections):
 
 ```yaml wrap
-Analyze this issue: "${{ needs.activation.outputs.text }}"
+Analyze this issue: "${{ steps.sanitized.outputs.text }}"
 ```
 
 ## Common IssueOps Patterns