[Code Quality] Document dispatch-workflow safe-output error messages

[github-actions]

Description

The dispatch-workflow safe-output has 3 security-critical error messages for validation, but NONE are documented in the error reference guide. Users encountering these errors have no documentation to reference.

Current State

• Implementation: pkg/workflow/dispatch_workflow.go (errors implemented)
• Documentation: docs/src/content/docs/troubleshooting/errors.md (missing section)
• Impact: Users encountering infinite loop prevention, compilation dependencies, or path traversal security checks have no guidance

Missing Error Messages

1. Self-Reference Prevention

dispatch-workflow: self-reference not allowed (workflow '%s' cannot dispatch itself)
```
**Cause**: Workflow attempts to dispatch itself, creating infinite loop  
**Security Impact**: Prevents infinite execution loops

### 2. Compilation Dependency Check
```
dispatch-workflow: workflow '%s' must be compiled first (run 'gh aw compile %s')
```
**Cause**: Target workflow not yet compiled to `.lock.yml` file  
**User Action**: Run `gh aw compile (workflow-name)` first

### 3. Path Traversal Protection
```
dispatch-workflow: invalid workflow name '%s' (path traversal not allowed)

Cause: Workflow name contains .. or path traversal characters
Security Impact: Prevents directory traversal attacks

Suggested Changes

Add a new section to docs/src/content/docs/troubleshooting/errors.md:

Safe Output Errors → dispatch-workflow

### dispatch-workflow Safe Output Errors

#### Self-Reference Not Allowed

**Error Message:**
\`\`\`
dispatch-workflow: self-reference not allowed (workflow 'my-workflow' cannot dispatch itself)
\`\`\`

**Cause:** A workflow is attempting to dispatch itself, which would create an infinite loop.

**Solution:** 
- Use a different workflow for the dispatch target
- If you need recursive behavior, use a parent workflow that dispatches to child workflows
- Consider using workflow conditions to prevent infinite loops

**Example:**
\`\`\`yaml
# ❌ INCORRECT - Will fail
safe-outputs:
  dispatch-workflow:
    workflow: my-workflow  # This IS my-workflow!

# ✅ CORRECT - Dispatch to different workflow
safe-outputs:
  dispatch-workflow:
    workflow: child-workflow
\`\`\`

---

#### Workflow Must Be Compiled First

**Error Message:**
\`\`\`
dispatch-workflow: workflow 'target-workflow' must be compiled first (run 'gh aw compile target-workflow')
\`\`\`

**Cause:** The target workflow has not been compiled to a `.lock.yml` file yet.

**Solution:**
1. Compile the target workflow: `gh aw compile target-workflow.md`
2. Verify `.lock.yml` exists: `ls .github/workflows/target-workflow.lock.yml`
3. Commit both files to the repository

---

#### Path Traversal Not Allowed

**Error Message:**
\`\`\`
dispatch-workflow: invalid workflow name '../../../etc/passwd' (path traversal not allowed)
\`\`\`

**Cause:** Workflow name contains directory traversal characters (`..`, absolute paths).

**Solution:**
- Use only the workflow basename (e.g., `my-workflow`, not `../my-workflow`)
- Workflow files must be in `.github/workflows/` directory
- Remove any path separators or `..` from workflow names

**Example:**
\`\`\`yaml
# ❌ INCORRECT - Path traversal attempt
safe-outputs:
  dispatch-workflow:
    workflow: ../../malicious-workflow

# ✅ CORRECT - Simple workflow name
safe-outputs:
  dispatch-workflow:
    workflow: deploy-prod
\`\`\`

Files Affected

• MODIFY: docs/src/content/docs/troubleshooting/errors.md (add new section)

Success Criteria

• New "dispatch-workflow Safe Output Errors" section added
• All 3 error messages documented with:
  • Error message example
  • Cause explanation
  • Solution steps
  • Code examples (incorrect vs. correct)
• Security context explained for self-reference and path traversal
• Documentation builds successfully
• Links to dispatch-workflow guide added (if exists)

Source

Extracted from Error Documentation Consistency Check discussion #12133

Quote from report:

dispatch-workflow Errors Completely Missing

Severity: Critical - Security-related feature

The dispatch-workflow safe-output has comprehensive validation with 3 security-critical error messages, but NONE are documented

Priority

HIGH - Security-related errors should be well-documented to help users understand the protection mechanisms.

Estimated Effort

1-2 hours (write documentation, add examples, validate build)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 18, 2026, 1:30 AM UTC