[spdd] Daily spec work plan - 2026-08-20

[github-actions]

Summary

Daily SPDD review of 5 spec files (rotation index 0–4 of 19 total under specs/, scratchpad/, and docs/src/content/docs/reference/*specification*.md). No *specification*.md files exist yet under docs/src/content/docs/reference/, so scope was scratchpad/ (3 files) + specs/ (start of alphabetical list, 2 files). Overall specs are in good shape (well-structured REASONS sections, RFC 2119 language, conformance tests), but there are concrete gaps: two scratchpad files are stale/deprecated with pending removal work, and the awf-config-sources-spec.md REASONS canvas is missing an explicit Entities/Requirements heading split despite having the content inline.

Priority Work Queue

• P0: Track and execute the scheduled deletion of scratchpad/safe-outputs-specification.md (deprecated, scheduled for removal on/before 2026-09-21) via the tracked checklist in specs/safe-outputs-scratchpad-removal.md.
• P1: Verify scratchpad/github-mcp-access-control-specification.md (v1.1.0, Draft) is not silently diverging from its canonical MCP Gateway implementation; add a Sync Follow-up note if not already tracked.
• P1: Add an explicit ## Sync Follow-ups section to specs/awf-config-sources-spec.md (currently only has "Norms"/"Safeguards" under §6/§8; no standalone Sync Follow-ups heading despite drift-detection procedure content in §7).
• P2: Tighten guard-policies-specification.md §"Open Questions" (line 390) into either resolved decisions or explicit follow-up tasks; an unresolved Open Questions section this late in a Draft spec is a risk marker.
• P2: Cross-link specs/awf-config-sources-compliance/README.md conformance test IDs (T-DR-001..010, T-DR-SAFE-001..004) back to spec section anchors to keep spec/test traceability current.

SPDD Checklist

• Execute the removal checklist in specs/safe-outputs-scratchpad-removal.md and confirm scratchpad/safe-outputs-specification.md references are updated to the canonical docs/src/content/docs/specs/safe-outputs-specification.md path (target: 2026-09-21 deadline). Done when: no remaining internal links point to the scratchpad file.
• Diff scratchpad/github-mcp-access-control-specification.md §4.4 (Access Control Extension Fields) against the current MCP Gateway implementation in pkg/workflow/ for field-name drift (e.g., repos vs allowed-repos). Done when: a Sync Notes entry is added confirming parity or listing discrepancies.
• Add a ## Sync Follow-ups section to specs/awf-config-sources-spec.md describing what to update in specs/awf-config-sources-compliance/README.md after any §3.1 DriftRecord schema change. Done when: section exists with at least one actionable trigger condition.
• Resolve or convert guard-policies-specification.md "Open Questions" (around line 390) into dated follow-up tasks in the ## Sync Follow-ups section (line 588). Done when: no bare unresolved question remains without an owner or target date.
• Update specs/awf-config-sources-compliance/README.md table rows (T-DR-001..010) to include section anchor links (e.g., ../awf-config-sources-spec.md#31-driftrecord) instead of bare §3.1 text references. Done when: every test row links to a spec anchor.
• Verify scratchpad/guard-policies-specification.md §"Deprecation: repos Field" (line 473) and GP-S004 safeguard (line 533) agree on migration timeline language; reconcile wording if they conflict. Done when: both sections state the same deprecation window.
• Confirm pkg/workflow/awf_config_drift_test.go implements all 10 T-DR test IDs and 4 T-DR-SAFE test IDs listed in specs/awf-config-sources-compliance/README.md. Done when: a grep -c "T-DR" count in the test file matches or exceeds 14.
• Add explicit ISO 8601 timestamp format examples to specs/awf-config-sources-spec.md §3.1.1 detected_at field definition to remove ambiguity flagged by T-DR-003. Done when: schema section includes at least one valid/invalid example pair.

Per-Spec Findings

scratchpad/github-mcp-access-control-specification.md (v1.1.0, Draft, 2873 lines)

Analysis: Comprehensive access-control spec for the GitHub MCP Server covering repo scoping, roles, private-repo controls, and integrity levels. Strong RFC 2119 usage and a large Appendix of examples (A.1–A.14) and error codes (B.1–B.8). Sync Notes and Sync Follow-ups exist (lines 2739, 2774) with a "Divergence Audit (2026-06-21)" entry — good practice already in place.

REASONS gaps: Requirements/Conformance/Architecture/Structure/Operations are all well covered (§1–§10). Safeguards are implicit inside §9 Security Model and Appendix C rather than a dedicated ## Safeguards heading — consider promoting to a top-level heading for consistency with other specs (e.g., guard-policies-specification.md has an explicit ## Safeguards section).

scratchpad/guard-policies-specification.md (v0.1.0, Draft, 622 lines)

Analysis: Proposal-style doc for guard policies (allowed-repos, min-integrity) in the MCP Gateway, with extensibility for future servers. Has clean Entities, Conformance, Safeguards (GP-S001–GP-S005), Sync Notes, and Sync Follow-ups sections — a good REASONS template.

REASONS gaps: "Open Questions" (line 390) remains unresolved this deep into a document that already has a Conclusion (line 414); this should be resolved before promoting past Draft. No explicit "Norms" heading (RFC 2119 language is used inline but not labeled).

scratchpad/safe-outputs-specification.md (v1.1.0, DEPRECATED, 1303 lines)

Analysis: Explicitly deprecated in favor of canonical v1.28.3 at docs/src/content/docs/specs/safe-outputs-specification.md, with a hard deletion deadline of 2026-09-21 and a tracked removal checklist (specs/safe-outputs-scratchpad-removal.md). This is the highest-risk item in this batch purely due to the approaching deadline.

REASONS gaps: N/A for content quality (deprecated) — the only actionable gap is operational: confirming the removal checklist is actually being executed and that navigation/doc-site links are being redirected ahead of the deadline.

specs/awf-config-sources-compliance/README.md (81 lines)

Analysis: Conformance fixture README listing 10 DriftRecord test IDs (T-DR-001–010) and 4 safeguard test IDs (T-DR-SAFE-001–004), all mapped to pkg/workflow/awf_config_drift_test.go / awf_config_safeguards_formal_test.go. Good machine-checkable structure.

REASONS gaps: Test ID rows reference spec sections as bare text (§3.1, §7.5.1, §8) rather than as links, making spec/test navigation harder. No "Structure" or "Operations" framing — this is purely a fixture-tracking doc, which is appropriate for its scope, but it should link back to the parent spec more explicitly.

specs/awf-config-sources-spec.md (v0.1.0, Working Draft, 314 lines)

Analysis: Defines canonical AWF config sources in github/gh-aw-firewall that agents must consult, the DriftRecord schema (§3.1), a drift detection procedure (§7), and SLA escalation (CR-06). Has ## 8. REASONS Canvas with a ### Safeguards subsection but no matching ### Requirements, ### Entities, ### Approach, ### Structure, ### Operations, or ### Norms subsections under that same canvas heading — the REASONS canvas is incomplete relative to its own heading name.

REASONS gaps: Missing explicit ### Norms under §6 Conformance Requirements (only has a bare "Norms" sub-bullet per earlier grep, not a full norms writeup). Missing dedicated ## Sync Follow-ups heading — drift procedure content exists in §7 but no explicit "what to update after a change" guidance separate from the drift detection procedure itself.

Sync Follow-ups

• After specs/awf-config-sources-spec.md §3.1 DriftRecord schema changes, update specs/awf-config-sources-compliance/README.md test ID descriptions and pkg/workflow/awf_config_drift_test.go/awf_config_safeguards_formal_test.go in lockstep.
• After scratchpad/safe-outputs-specification.md deletion (target 2026-09-21), sweep the repo for any remaining links to the scratchpad path and redirect them to docs/src/content/docs/specs/safe-outputs-specification.md.
• After resolving Open Questions in scratchpad/guard-policies-specification.md, promote the guard-policies proposal out of scratchpad into specs/ once implementation lands, mirroring the awf-config-sources-spec.md structure.
• After any repos → allowed-repos field rename lands in code, update GP-S004 in guard-policies-specification.md and the corresponding section in github-mcp-access-control-specification.md §4.4.1 together to avoid divergence.

Context

• Files reviewed this run (rotation index 0–4 of 19):
  1. scratchpad/github-mcp-access-control-specification.md
  2. scratchpad/guard-policies-specification.md
  3. scratchpad/safe-outputs-specification.md
  4. specs/awf-config-sources-compliance/README.md
  5. specs/awf-config-sources-spec.md
• Rotation state: no prior rotation.json found in cache-memory (confirmed absent, not a read error) — initialized fresh from index 0. Next run should continue from index 5 (specs/compiler-threat-detection-compliance/README.md).
• Total spec files in scope: 19 (specs/**/*.md: 15, scratchpad/*specification*.md: 3, docs/src/content/docs/reference/*specification*.md: 0 found).
• Run URL: https://github.com/github/gh-aw/actions/runs/32389435926

Generated by 📋 Daily SPDD Spec Planner · auto · 23.1 AIC · ⌖ 5.45 AIC · ⊞ 7.3K · ◷

• expires on Aug 23, 2026, 8:05 AM UTC-08:00

[github-actions]

This issue was automatically closed because it expired on 2026-08-23T16:05:10.787Z.

Closed by Workflow