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

[github-actions]

Summary

Daily SPDD review of 5 specification files (rotation index 0–4 of 19 tracked spec files; next run resumes at index 5). Two scratchpad specs (github-mcp-access-control-specification.md, safe-outputs-specification.md) are large, mature, mostly-consistent documents with active Sync Notes/Sync Follow-ups sections already in place. guard-policies-specification.md is well-formed with a resolved Open Questions section and its own Sync Follow-ups. The awf-config-sources-spec.md + compliance README pair is small, internally consistent, and cross-referenced correctly. No P0 spec-breaking gaps were found, but several REASONS-canvas weaknesses and stale cross-references were identified below.

Priority Work Queue

• P0: None identified this run.
• P1: Resolve the remaining open question in github-mcp-access-control-specification.md §9.7 (dry-run report lockdown indicator) — verify pkg/cli/compile_guard_policy_report.go actually emits the lockdown field described as "implemented," since the spec claims completion but no compliance test ID is cross-referenced for it.
• P1: Reconcile the repos vs allowed-repos naming divergence noted in the Divergence Audit (§Sync Notes, github-mcp-access-control-specification.md) — confirm specs/github-mcp-access-control-compliance/README.md fixtures consistently use allowed-repos per the "Resolved" status claim.
• P2: Add missing ### Safeguards and ### Norms-equivalent sections to awf-config-sources-spec.md (currently only has §8 "Safeguards" as a numbered section, not framed under REASONS headers) for consistency with the REASONS canvas used elsewhere.
• P2: Tighten Operations-order language in guard-policies-specification.md §4 (MCP Gateway Configuration Flow) to explicitly state guard-policy validation MUST run before compilation completes, not just "during compilation."

SPDD Checklist

• github-mcp-access-control-specification.md (§9.7, Open Questions): Verify pkg/cli/compile_guard_policy_report.go emits the lockdown indicator in --strict dry-run output as claimed. Done when: a passing test in pkg/cli/ asserts the lockdown field appears in the report output, or the spec is corrected to remove the "implemented" claim. (stage: /spdd-sync)
• github-mcp-access-control-specification.md (§Sync Notes, Divergence Audit): Confirm pkg/workflow/tools_validation_test.go and specs/github-mcp-access-control-compliance/README.md fixtures use allowed-repos (not the deprecated repos alias) in all new/updated test cases. Done when: a grep of the compliance fixture directory shows no new repos:-only test cases without an allowed-repos equivalent. (stage: /spdd-sync)
• guard-policies-specification.md (§GP-11, Conformance): Clarify whether allowed-repos: "all" explicitly requires min-integrity — current wording is a MAY, creating ambiguity for implementers. Done when: the spec states a definitive MUST/MAY and pkg/workflow/tools_validation_github.go matches the chosen requirement. (stage: /spdd-analysis)
• guard-policies-specification.md (§Operations, item 1): Add explicit ordering guarantee that frontmatter parsing (tools_parser.go) always precedes validation (tools_validation.go) in the same compiler pass. Done when: the Operations section states this invariant and links to the compiler orchestration call site (compiler_orchestrator_workflow.go). (stage: /spdd-generate)
• safe-outputs-specification.md (§3.6 Entities): Add a REASONS-canvas "Norms" cross-reference note linking 2.4 Norms to the entity definitions in 3.6, since currently these sections are disconnected. Done when: §3.6 entities each cite which norm(s) in §2.4 they satisfy. (stage: /spdd-reasons-canvas)
• awf-config-sources-spec.md (§8 Safeguards): Restructure to use an explicit ### Safeguards header (currently ## 8. Safeguards) consistent with guard-policies-specification.md's REASONS-canvas style, to ease canvas-based navigation. Done when: heading style matches sibling specs and a TOC entry is added. (stage: /spdd-generate)
• awf-config-sources-compliance/README.md: Add a T-DR-011+ placeholder row guidance example showing how to cross-reference a safeguard test (not just DriftRecord schema tests) since current table only documents T-DR-SAFE-001..004 without a "how to add a new safeguard test" walkthrough. Done when: a short "Adding New Safeguard Conformance Tests" subsection exists parallel to the existing DriftRecord one. (stage: /spdd-generate)
• github-mcp-access-control-specification.md (§8.5 Combined Evaluation Order / Sync Follow-ups): Verify the production gateway repo (external, not in this repo) has been updated to match any recent P5/P6 predicate-order changes; the spec sync-follow-up assumes cross-repo alignment but there is no automated check in this repo enforcing it. Done when: an issue is filed against/confirmed with the gateway repo tracking this, or a comment note is added here that the gateway is already in sync. (stage: /spdd-sync)

Per-Spec Findings

scratchpad/github-mcp-access-control-specification.md (2871 lines)

• Analysis: Comprehensive, RFC-2119-compliant access control spec covering 7 extension fields (repos/allowed-repos, roles, private-repos, min-integrity, blocked-users, trusted-users, approval-labels). Well-structured with Conformance Classes, Architecture, Configuration Format, Compliance Testing, and Appendices.
• Risks: The Divergence Audit (§Sync Notes) documents naming inconsistency between repos (internal/legacy) and allowed-repos (frontmatter) — marked "Resolved" but worth periodic re-verification since it's a common source of confusion for new contributors.
• REASONS gaps: Has strong Requirements (§2 Conformance), Entities (§4.2–4.4 fields), Approach/Structure (§3 Architecture), Operations (§10 Integration), and explicit Safeguards (§9.6). Missing a distinct "Norms" section — normative language is scattered rather than centralized.
• Sync: §Sync Follow-ups (lines 2774–2800) already define concrete file-update triggers for §8.5 and §4.4 changes — no action needed beyond periodic verification that the referenced test files still exist and pass.

scratchpad/guard-policies-specification.md (621 lines)

• Analysis: Focused proposal-turned-spec for GitHub guard policies (allowed-repos, min-integrity) with extensibility for future MCP servers (Jira, WorkIQ). All four Open Questions are resolved with decision records — good practice.
• Risks: GP-11's phrasing ("MAY enforce the same requirement for explicit allowed-repos: 'all'") introduces implementer ambiguity about whether min-integrity is required alongside allowed-repos: "all".
• REASONS gaps: Requirements (§Conformance GP-01–GP-11) and Safeguards (§GP-S001–S005) are strong. Entities section (added) is solid. Operations (§4 MCP Gateway Configuration Flow) could be tightened to state explicit ordering guarantees between parsing and validation steps.
• Sync: Sync Notes and Sync Follow-ups sections are present and current (last verified 2026-07-03) with concrete file-level mappings.

scratchpad/safe-outputs-specification.md (1297 lines)

• Analysis: Broad specification covering the 4-layer safe-outputs architecture (frontmatter config, MCP server, validation guardrails, execution handlers), builtin tools (missing-tool, missing-data, noop), and GitHub operations catalog.
• Risks: No major risks found; document is mature (Version 1.1.0 Recommendation per Change Log).
• REASONS gaps: Has Norms (§2.4) and Entities (§3.6: SafeOutputRequest, GuardrailViolation, ExecutionResult) as distinct sections, which is good practice other specs in this rotation lack. However, the connection between Norms and Entities is implicit rather than explicit — entities don't cite which norms they enforce.
• Sync: No dedicated "Sync Notes"/"Sync Follow-ups" section was found in the header scan for this file (unlike the other two scratchpad specs) — worth adding in a future generate/sync pass to match sibling spec conventions.

specs/awf-config-sources-compliance/README.md (74 lines) & specs/awf-config-sources-spec.md (293 lines)

• Analysis: Small, tightly-scoped pair defining the DriftRecord entity schema (§3.1/§6.5) and its conformance test fixtures (T-DR-001...010, T-DR-SAFE-001...004). Cross-references between spec and fixture README are accurate and bidirectional.
• Risks: Low risk — this is one of the best-synchronized spec/fixture pairs reviewed. The "Structure" section (§Structure) explicitly declares the three-member conformance unit (spec, fixture index, Go test file) and the sync obligation.
• REASONS gaps: Requirements (§6 Conformance CR-01–CR-06a) and Safeguards (§8, T-DR-SAFE-*) are both strong and well-tested. Entities (§3.1 DriftRecord) is a single well-formed entity. Missing: an explicit "Norms" framing (RFC 2119 language is present but not called out as a distinct section) and the "Adding New Conformance Tests" guidance (README §Adding New Conformance Tests) only covers DriftRecord schema tests, not safeguard (T-DR-SAFE-*) tests.
• Sync: Fixture README's "Spec Reference" and "Running Conformance Tests" sections give clear file paths and test-run commands — good sync hygiene.

Sync Follow-ups

• After any change to github-mcp-access-control-specification.md §8.5 (combined P5/P6 evaluation order), confirm the external gateway implementation (outside this repo) has been updated in lockstep — this repo's formalEvaluateAccess in pkg/workflow/github_mcp_access_control_formal_test.go is a test-only mirror, not the source of truth.
• After any change to guard-policies-specification.md §GP-01–GP-11, update pkg/workflow/schemas/mcp-gateway-config.schema.json AND docs/public/schemas/mcp-gateway-config.schema.json together (both copies must stay in sync per the spec's own Sync Follow-ups section).
• Consider adding a ### Sync Notes / ### Sync Follow-ups section pair to safe-outputs-specification.md mirroring the other two scratchpad specs, so future SPDD runs can programmatically verify code/spec alignment for the 4-layer architecture and builtin tools.
• Re-verify the "Resolved" Divergence Audit entries in github-mcp-access-control-specification.md (dated 2026-06-21) are still accurate; the audit is over a month old relative to spec's "Last Updated" cadence elsewhere and should be re-dated or re-confirmed on the next full rotation pass.

Context

Files reviewed this run (rotation index 0–4 of 19, next run resumes at index 5):

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: persisted to /tmp/gh-aw/cache-memory/spdd-daily/rotation.json (last_index: 5, total_files: 19). No prior rotation file existed (confirmed absent before initializing).

Run URL: https://github.com/github/gh-aw/actions/runs/31957063541

Generated by 📋 Daily SPDD Spec Planner · auto · 43.5 AIC · ⌖ 2.47 AIC · ⊞ 7.1K · ◷

• expires on Aug 19, 2026, 8:01 AM UTC-08:00