Tighten reference docs for artifact compatibility, audit JSON contracts, and safe-output safeguards#47117
Merged
Merged
Conversation
11 tasks
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Update reference documentation for correctness and safeguards
Tighten reference docs for artifact compatibility, audit JSON contracts, and safe-output safeguards
Jul 21, 2026
This comment has been minimized.
This comment has been minimized.
Contributor
🤖 PR Triage
Score breakdown: Impact 12 · Urgency 8 · Quality 8
|
Contributor
🎉 Excellent Work!This PR is well-aligned with the project's contribution standards. The documentation updates are focused, comprehensive, and improve clarity across multiple reference pages:
The changes are focused, coherent, and thoroughly documented in the PR body. The implementation is ready for review by maintainers.
|
pelikhan
approved these changes
Jul 22, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Tightens reference documentation around compatibility, JSON contracts, billing, MCP safeguards, and cross-repository safe outputs.
Changes:
- Documents legacy artifacts and JSON field availability.
- Adds billing estimation and MCP permission-cache guidance.
- Expands safe-output stability criteria and cross-reference links.
Show a summary per file
| File | Description |
|---|---|
artifacts.md |
Adds compatibility and source annotations. |
audit.md |
Clarifies JSON contracts and ambient context. |
billing.md |
Adds billing permission and estimation guidance. |
gh-aw-as-mcp-server.md |
Documents actor validation and caching. |
safe-outputs-pull-requests.md |
Adds graduation criteria and related links. |
cross-repository.md |
Adds reverse PR safe-output linkage. |
smoke-call-workflow.lock.yml |
Reduces reusable-workflow Actions permission. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 7/7 changed files
- Comments generated: 3
- Review effort level: Medium
|
|
||
| ```bash | ||
| gh aw logs my-workflow --last 5 --json \ | ||
| | jq '.per_run_breakdown[] | {run_id, aic, action_minutes}' |
| The report output includes an executive summary, domain inventory, metrics trends, MCP server health, and per-run breakdown. It detects cross-run anomalies such as domain access spikes, elevated MCP error rates, and connection rate changes. | ||
|
|
||
| For each run in detailed logs JSON output, an `ambient_context` object is included when token usage data is available. It reflects only the first LLM invocation in the run (`input_tokens`, `cached_tokens`, and legacy `effective_tokens`). | ||
| For each run in detailed logs JSON output, an `ambient_context` object is included when token usage data is available. It reflects only the first LLM invocation in the run (`input_tokens`, `cached_tokens`, and legacy `effective_tokens`). It is absent when the downloaded artifacts do not contain usable `token-usage.jsonl` or fallback `agent_usage.json` data for that run. |
| | `agent` | `constants.AgentArtifactName`<br/>Source: `pkg/constants/job_constants.go` | Multi-file | Unified agent job outputs (logs, safe outputs, token usage summary) | | ||
| | `activation` | `constants.ActivationArtifactName` | Multi-file | Activation job output (`aw_info.json`, `prompt.txt`, rate limits) | | ||
| | `firewall-audit-logs` | `constants.FirewallAuditArtifactName` | Multi-file | AWF firewall audit/observability logs (token usage, network policy, audit trail) | | ||
| | `firewall-audit-logs` | `constants.FirewallAuditArtifactName`<br/>Source: `pkg/constants/constants.go` | Multi-file | AWF firewall audit/observability logs (token usage, network policy, audit trail) | |
Contributor
|
🎉 This pull request is included in a new release. Release: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This updates the SPDD reference pages that had gaps in safeguards, norms, and sync coverage. The changes make legacy behavior, missing-field conditions, experimental status, and cross-spec linkages explicit in the high-traffic docs most likely to be consumed directly.
Artifacts reference
safe-outputandagent-outputartifacts, including migration guidance toward the unifiedagentartifact and a removal floor.pkg/constants/....agentandfirewall-audit-logsrows with their implementation source.Audit reference
--jsonstability contract next to the--jsonflag docs for bothgh aw auditandgh aw logs.ambient_contextis absent instead of leaving it as an implicit “when available” field.Billing reference
gh aw compiledoes not auto-injectpermissions.copilot-requests: write; authors must declare it unless a higher-level authoring flow adds it explicitly.GH-AW as MCP server
--validate-actorbehavior whenGITHUB_ACTORis unset: privileged tools remain mounted but return permission errors.Safe outputs / pull requests
merge-pull-request.head-repo/ fork flows.Cross-repository reference
Example of the clarified JSON contract placement: