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

[github-actions]

Summary

Daily SPDD review of 5 specification files (rotation index 10–14): specs/safe-output-outcome-evaluation.md, specs/security-architecture-spec-summary.md, specs/security-architecture-spec-validation.md, specs/security-architecture-spec.md, and scratchpad/github-mcp-access-control-specification.md. All five are mature, actively-maintained specs. No missing-Norms crisis was found, but several REASONS-canvas gaps and stale sync/validation debts exist that should be closed to keep spec and implementation aligned.

Priority Work Queue

• P0: Re-run the Security Architecture validation pass — specs/security-architecture-spec-validation.md re-validation triggers (companion spec changes) are due since scratchpad/github-mcp-access-control-specification.md shows an unresolved heading/field-naming divergence (repos vs allowed-repos) that could affect §3.2/§9 claims.
• P1: Close the three "Minor Discrepancies" items in specs/security-architecture-spec-validation.md (Pre-Activation job, Detection job naming, Conclusion job) by adding explicit notes to specs/security-architecture-spec.md Appendix D.
• P1: Add explicit Sync Follow-ups entries in specs/safe-output-outcome-evaluation.md — currently it has Norms/Provenance Limits but no dedicated "Sync Follow-ups" or "Structure" section mapping outcome types to implementation files, unlike its sibling specs.
• P2: Tighten Operations-order language across scratchpad/github-mcp-access-control-specification.md §8.5 to reduce ambiguity flagged in its own Sync Follow-ups section.

SPDD Checklist

• /spdd-analysis: Review specs/security-architecture-spec-validation.md re-validation triggers section and confirm whether trigger #3 (companion guard-policy spec changes) has already fired due to the repos/allowed-repos divergence noted in scratchpad/github-mcp-access-control-specification.md. Done when a decision (re-validate or defer with rationale) is recorded in the validation doc's Re-validation Triggers section.
• /spdd-reasons-canvas: Add a "Structure" subsection to specs/safe-output-outcome-evaluation.md mapping each of the 22 safe-output-type sections (create_pull_request, create_issue, etc.) to their implementing Go files under pkg/workflow/. Done when every numbered section has a corresponding implementation-file reference.
• /spdd-reasons-canvas: Add explicit "Safeguards" language to specs/security-architecture-spec-summary.md Appendix H (Security Best Practices) clarifying which guarantees are enforced at compile time vs. runtime. Done when Appendix H distinguishes compile-time vs runtime enforcement for each listed practice.
• /spdd-generate: Update specs/security-architecture-spec.md Appendix D (Safe Output Configuration Examples) to include example job structures for pre_activation, detection, and conclusion jobs per the three Minor Discrepancies in specs/security-architecture-spec-validation.md. Done when Appendix D shows all three job types in an example lock-file excerpt.
• /spdd-generate: Implement/verify a compile-time warning test in pkg/workflow/tools_validation_github.go for the allowed-repos/repos deprecated-alias path referenced in the Divergence Audit of scratchpad/github-mcp-access-control-specification.md. Done when go test ./pkg/workflow/ -run TestValidateGitHub passes with a case exercising the alias.
• /spdd-generate: Add a concrete rate-limit backoff example (code or config snippet) to §C.4 of scratchpad/github-mcp-access-control-specification.md. Done when the section includes an executable or pseudo-code backoff example, not just prose bullets.
• /spdd-sync: Update specs/github-mcp-access-control-compliance/README.md Formal Model and Behavioral Coverage Map if §8.5 predicate order in scratchpad/github-mcp-access-control-specification.md is touched, per its own "After Changing §8.5" sync follow-up. Done when README tables match the spec's current P1–P6 predicate order.
• /spdd-sync: Cross-check specs/security-architecture-spec-validation.md "Specification Accuracy Summary" table rows against current pkg/workflow implementation locations (e.g., sanitize_content_core.cjs, checkout_pr_branch.cjs) to confirm none have moved. Done when each evidence-location cell is re-verified with a file existence check and the table is updated if any path changed.
• /spdd-sync: Re-run go test ./pkg/workflow/ -run TestValidateGitHub after any §4.4 field change in scratchpad/github-mcp-access-control-specification.md per its own Sync Notes procedure. Done when test output is attached to the PR that made the field change.

Per-Spec Findings

specs/safe-output-outcome-evaluation.md

Analysis: Well-defined Principles, Norms (RFC 2119), Provenance Limits, and Outcome Categories for 22+ safe-output types. Goals are clear (measurable outcomes, bot-aware classification, time-bounded checks). No obvious ambiguous requirements found in Norms section.

REASONS gaps: Missing an explicit "Structure" section mapping each outcome type to its Go/JS implementation file (other specs in this batch include implementation-file tables). No "Safeguards" section discussing failure modes if the 48-hour delay window is bypassed or misconfigured.

Generate targets: Add file-mapping table near "Implementation" (line 73); add a Safeguards subsection after Provenance Limits.

specs/security-architecture-spec-summary.md

Analysis: Solid overview/index document with Conformance Classes, Security Guarantees, Formal Model, and Appendices A–H. Structure and Norms are strong given it's a summary of the full spec.

REASONS gaps: Appendix H (Security Best Practices) doesn't distinguish compile-time vs runtime enforcement — an Operations-ordering ambiguity for readers trying to know when a guarantee is actually checked.

Generate targets: Annotate Appendix H entries with [compile-time] / [runtime] tags.

specs/security-architecture-spec-validation.md

Analysis: Detailed validation evidence table (Section-by-section) with re-validation triggers and failure escalation procedure. Strong Norms (MUST-level escalation steps) and Operations (re-validation procedure).

REASONS gaps: Three "Minor Discrepancies" (pre_activation job, detection job naming, conclusion job) are documented but not yet folded back into the main security-architecture-spec.md Appendix D examples — a Sync gap between validation doc and source spec.

Generate targets: Close the three discrepancies in the source spec's Appendix D; then re-run the Detailed Validation procedure per the Re-validation Triggers section.

specs/security-architecture-spec.md

Analysis: Large normative spec (Conformance Classes, multi-layer architecture, Input Sanitization procedures, etc.). Requirements and Entities sections are thorough through Section 4 (viewed range).

REASONS gaps: Appendix D (Safe Output Configuration Examples) referenced by the validation doc as needing pre_activation/detection/conclusion job examples — currently likely incomplete per validation doc's own recommendation.

Generate targets: Expand Appendix D per validation doc recommendations #2 and #3.

scratchpad/github-mcp-access-control-specification.md

Analysis: Comprehensive access-control spec (Conformance, Architecture, Configuration Format, extensive Appendix examples A–C, Sync Notes, Divergence Audit, Sync Follow-ups, Change Log). Very strong REASONS coverage overall — this is the most complete spec in the batch.

REASONS gaps: §C.4 Rate Limit Considerations is prose-only bullets with no concrete backoff example (weak "Approach" concreteness). The Divergence Audit flags a resolved-but-still-noteworthy repos/allowed-repos naming inconsistency between frontmatter and internal gateway field that should be watched for regression.

Generate targets: Add executable backoff example to §C.4; add a regression test asserting allowed-repos alias resolution in pkg/workflow/tools_validation_github.go.

Sync Follow-ups

• After closing the three Minor Discrepancies in the validation doc, re-run the Detailed Validation procedure and update the Specification Accuracy Summary table (per the doc's own "Re-validation Triggers" → Normative Triggers #1/#2).
• After adding the Structure/Safeguards sections to specs/safe-output-outcome-evaluation.md, verify none of the 22 safe-output-type sections were left without an implementation-file reference.
• After any §8.5 predicate-order change in scratchpad/github-mcp-access-control-specification.md, update specs/github-mcp-access-control-compliance/README.md Formal Model and its associated combined-blocked-integrity.yaml test fixture per that spec's own documented sync procedure.
• Confirm go test ./pkg/workflow/ -run TestValidateGitHub passes after the allowed-repos alias regression test is added.

Context

Files reviewed this run (rotation indices 10–14 of 17 total):

1. specs/safe-output-outcome-evaluation.md
2. specs/security-architecture-spec-summary.md
3. specs/security-architecture-spec-validation.md
4. specs/security-architecture-spec.md
5. scratchpad/github-mcp-access-control-specification.md

Rotation state: last_index advanced 10 → 15 (of 17 total files tracked in all_files_ordered); next run continues at scratchpad/guard-policies-specification.md (index 15) and scratchpad/safe-outputs-specification.md (index 16), then wraps to index 0.

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

Generated by 📋 Daily SPDD Spec Planner · auto · 25.7 AIC · ⌖ 2.35 AIC · ⊞ 6.8K · ◷

• expires on Aug 16, 2026, 8:14 AM UTC-08:00