[spdd] Daily spec work plan - 2026-07-21

[github-actions]

Summary

SPDD daily review covering 5 reference documentation files (indices 40–44): artifacts.md, audit.md, billing.md, gh-aw-as-mcp-server.md, and safe-outputs-pull-requests.md. These are high-traffic reference pages. Analysis reveals gaps in Safeguards, Norms, and Sync coverage across all five files — particularly around error paths, version constraints, and cross-spec linkage.

Priority Work Queue

P0 — Correctness / Safeguards

• artifacts.md: The safe-output and agent-output legacy artifact names are described as back-compat but there is no documented deprecation timeline or removal guard, risking silent breakage in downstream consumers.
• audit.md: ambient_context is documented as "when available" but the condition that makes it absent is unspecified — consumers can't reliably guard against missing fields.
• safe-outputs-pull-requests.md: merge-pull-request is experimental but the stability criteria / graduation path are not stated.

P1 — Completeness / REASONS gaps

• billing.md: No norms for estimating or capping costs before a run; the "Estimating" section only points to post-run tooling.
• gh-aw-as-mcp-server.md: Actor validation section lacks a norm for what happens when GITHUB_ACTOR is unset; permission cache TTL (1 hour) has no invalidation mechanism documented.
• audit.md: Cross-run JSON output field stability contract ("stable" vs "extended") is noted only at the bottom, away from the flags that produce it.

P2 — Sync / Maintenance

• All five files lack explicit sync notes linking back to implementation constants (constants.AgentArtifactName, etc.) — changes to constant values won't automatically surface as doc-update triggers.
• safe-outputs-pull-requests.md references cross-repository ops and fork credential minting but the linkage to cross-repository.md is one-directional only.

SPDD Checklist

• [Generate / artifacts.md] Add a deprecation notice block for safe-output and agent-output legacy artifact names stating the version they became legacy and the planned removal milestone. Done when: a :::caution[Deprecated] block with a version and migration note appears in the Legacy section.
• [Safeguards / audit.md] Document the precise condition under which ambient_context is absent (e.g., firewall disabled, AWF version < X, or no token-usage artifact). Done when: the ambient_context prose includes an explicit "absent when" clause.
• [Norms / billing.md] Add a pre-run cost estimation pattern (e.g., use gh aw audit on a dry-run or reference model pricing tables) to the Estimating section. Done when: at least one code/command example for pre-run estimation appears in billing.md.
• [Safeguards / gh-aw-as-mcp-server.md] Document fallback behavior when GITHUB_ACTOR is unset with --validate-actor. Done when: a note or warning block explains the default (error or open) when the env var is missing.
• [Operations / gh-aw-as-mcp-server.md] Document TTL invalidation for the permission cache — is there a manual flush? Does a restart invalidate it? Done when: the Actor Validation section explicitly states invalidation conditions beyond the 1-hour window.
• [Sync / artifacts.md] Add a "Sync note" callout linking each constants.*ArtifactName reference to its Go source file path so doc updates are triggered when constants change. Done when: at least the AgentArtifactName and FirewallAuditArtifactName rows include a source link or sync annotation.
• [Structure / audit.md] Move the JSON field stability contract ("Top-level fields are stable; nested sub-fields may be extended") to the top of the --json flag documentation, before the usage examples. Done when: the stability contract paragraph appears immediately after the --json flag row in both gh aw audit and gh aw logs flag tables.
• [Norms / safe-outputs-pull-requests.md] Add graduation criteria for merge-pull-request experimental status — what must be true for it to become stable? Done when: a note under the experimental caution block lists measurable criteria (e.g., test coverage, known issues resolved).
• [Sync / safe-outputs-pull-requests.md] Add a bidirectional link from the head-repo / fork section to cross-repository.md, and verify cross-repository.md links back. Done when: both pages reference each other in the Related Documentation section.
• [Analysis / billing.md] Confirm whether copilot_requests: write permission is automatically injected at compile time or must always be declared manually. If compile-time injection exists, document it; if not, add a lint/warning note. Done when: the billing page explicitly states whether the permission is auto-injected.

Per-Spec Findings

artifacts.md — REASONS gaps

REASONS Dimension	Status	Gap
Requirements	✅ Present	Artifact names and types well-listed
Entities	✅ Present	Constants, file paths documented
Approach	⚠️ Partial	Legacy artifact migration approach unclear
Structure	✅ Present	Directory trees provided
Operations	✅ Present	Download patterns with examples
Norms	❌ Missing	No deprecation timeline, no version guards for legacy names
Safeguards	❌ Missing	No warning when safe-output artifact is empty due to being superseded

Key risk: Downstream workflows silently getting no data when fetching safe-output instead of agent.

audit.md — REASONS gaps

REASONS Dimension	Status	Gap
Requirements	✅ Present	Commands, flags, use cases documented
Entities	⚠️ Partial	ambient_context fields lack presence conditions
Approach	✅ Present	Single vs diff mode described
Structure	✅ Present	JSON field top-level contract present (but buried)
Operations	✅ Present	Examples comprehensive
Norms	⚠️ Partial	Field stability note at bottom, not co-located with flags
Safeguards	❌ Missing	No guard documented for ambient_context absence

billing.md — REASONS gaps

REASONS Dimension	Status	Gap
Requirements	✅ Present	Two cost types explained
Entities	✅ Present	Billing paths per engine listed
Approach	⚠️ Partial	No pre-run estimation pattern
Structure	✅ Present	Organized by engine
Operations	⚠️ Partial	Post-run monitoring only
Norms	❌ Missing	No guardrails or cost cap guidance
Safeguards	⚠️ Partial	copilot_requests: write requirements stated but auto-injection status unclear

gh-aw-as-mcp-server.md — REASONS gaps

REASONS Dimension	Status	Gap
Requirements	✅ Present	Tools and modes documented
Entities	✅ Present	All tools described with parameters
Approach	✅ Present	HTTP vs stdio modes covered
Structure	✅ Present	Config options organized by host
Operations	✅ Present	Examples for each host type
Norms	❌ Missing	Undefined behavior when GITHUB_ACTOR unset
Safeguards	❌ Missing	Permission cache invalidation undocumented; no fallback for auth failures

safe-outputs-pull-requests.md — REASONS gaps

REASONS Dimension	Status	Gap
Requirements	✅ Present	All PR safe-output types listed
Entities	✅ Present	Fields documented thoroughly
Approach	✅ Present	Bundle vs patch transport explained
Structure	✅ Present	Well-organized with cross-refs
Operations	✅ Present	Policy semantics, runtime overrides
Norms	⚠️ Partial	Experimental merge-pull-request has no graduation criteria
Safeguards	⚠️ Partial	Fork credential minting error paths not fully specified

Sync Follow-ups

• After updating deprecation notice in artifacts.md: verify cost-management.md and audit.md still reference the correct artifact names.
• After documenting ambient_context absence conditions in audit.md: check that otel-observability-spec.md (in specs/) aligns with the stated conditions.
• After billing.md pre-run estimation additions: sync with cost-management.md to avoid duplicate or contradictory guidance.
• After gh-aw-as-mcp-server.md actor validation updates: verify the copilot-setup-steps.yml generated by gh aw init sets GITHUB_ACTOR appropriately.
• After merge-pull-request graduation criteria are added: create a tracking issue or milestone for the graduation checklist.

Context

Field	Value
Files reviewed	artifacts.md, audit.md, billing.md, gh-aw-as-mcp-server.md, safe-outputs-pull-requests.md
Rotation index	40–44 of 688
Previous run	2026-07-20 (index 39)
Run URL	§29847927263

References: §29847927263

Generated by 📋 Daily SPDD Spec Planner · sonnet46 31 AIC · ⌖ 8.27 AIC · ⊞ 4.9K · ◷

• expires on Jul 24, 2026, 8:23 AM UTC-08:00