Tighten reference docs for artifact compatibility, audit JSON contracts, and safe-output safeguards

[Copilot]

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

  • Added a deprecation notice for legacy safe-output and agent-output artifacts, including migration guidance toward the unified agent artifact and a removal floor.
  • Added sync notes pointing doc maintenance back to the artifact-name constants in pkg/constants/....
  • Annotated the agent and firewall-audit-logs rows with their implementation source.

• Audit reference

  • Moved the --json stability contract next to the --json flag docs for both gh aw audit and gh aw logs.
  • Documented when ambient_context is absent instead of leaving it as an implicit “when available” field.
  • Kept the contract scoped to stable top-level fields and extensible nested payloads.

• Billing reference

  • Added a pre-run estimation pattern based on recent runs and published model tables.
  • Clarified that gh aw compile does not auto-inject permissions.copilot-requests: write; authors must declare it unless a higher-level authoring flow adds it explicitly.

• GH-AW as MCP server

  • Documented --validate-actor behavior when GITHUB_ACTOR is unset: privileged tools remain mounted but return permission errors.
  • Documented permission-cache invalidation semantics: in-memory only, 1h TTL, restart clears cache, no manual flush.

• Safe outputs / pull requests

  • Added explicit graduation criteria for experimental merge-pull-request.
  • Added the missing cross-repository linkage for head-repo / fork flows.
  • Added a Related Documentation section that points back to cross-repo and safe-output references.

• Cross-repository reference

  • Added the reverse link back to the PR safe-outputs reference to make the fork/target-repo docs bidirectional.

Example of the clarified JSON contract placement:

| `--json` | off | Output report as JSON to stdout |

Top-level fields in `--json` output are stable; nested sub-fields may be extended but are not removed without deprecation.

• Fixes [spdd] Daily spec work plan - 2026-07-21 #47116

[github-actions]

🤖 PR Triage

Field	Value
Category	docs
Risk	low
Score	28 / 100
Action	batch_review
Batch	—

Score breakdown: Impact 12 · Urgency 8 · Quality 8

Draft PR with documentation-only changes (6 reference docs + 1 lock file). Low urgency; no CI data. Recommend batching with other docs PRs.

Generated by 🔧 PR Triage Agent · sonnet46 43.3 AIC · ⌖ 5.33 AIC · ⊞ 5.6K · ◷

[github-actions]

🎉 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:

• Artifact compatibility — Deprecation notices and migration guidance for legacy artifacts
• Audit JSON contracts — Explicit stability guarantees and field availability documentation
• Billing & MCP server docs — Practical patterns and permission semantics
• Safe-output safeguards — Graduation criteria and cross-repository linkage

The changes are focused, coherent, and thoroughly documented in the PR body. The implementation is ready for review by maintainers.

Generated by ✅ Contribution Check · sonnet46 59 AIC · ⌖ 11.2 AIC · ⊞ 6.2K · ◷