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

[github-actions]

Summary

Rotation processed 5 spec files (index 10–14 of 19): specs/replace-label-spec.md, specs/safe-output-outcome-evaluation.md, specs/safe-outputs-scratchpad-removal.md, specs/security-architecture-spec-summary.md, specs/security-architecture-spec-validation.md. No critical breakage found, but a stale file-path reference, an approaching removal deadline, and a few weak REASONS sections need attention.

Priority Work Queue

• P0: Fix stale implementation-file references in specs/security-architecture-spec-summary.md (points to two Go files that no longer exist).
• P1: Track the scratchpad/safe-outputs-specification.md removal deadline (2026-09-21) — currently no automated check exists.
• P2: Strengthen Safeguards/Norms language in specs/replace-label-spec.md and specs/safe-output-outcome-evaluation.md; add explicit sync notes cross-linking the two docs.

SPDD Checklist

• /spdd-analysis: Verify pkg/workflow/safe_inputs_parser.go and pkg/workflow/safe_outputs_config.go referenced in specs/security-architecture-spec-summary.md (lines ~312-320); both are missing from the repo. Update the "Implementation Files" list to the correct current filenames. Done when the summary lists only files that exist in pkg/workflow/.
• /spdd-analysis: Confirm whether specs/safe-outputs-scratchpad-removal.md's 2026-09-21 deadline has an owner/tracking issue; if not, note the gap. Done when a linked tracking issue exists or the checklist item is annotated with an owner.
• /spdd-reasons-canvas (Safeguards): specs/replace-label-spec.md §8 (Security Considerations) covers allowlists and token scope well but doesn't state a MUST/SHOULD norm for handling a label_to_add that collides with a protected/blocked label mid-flight (race between allowlist check and PUT call). Done when §8.1/§8.6 add an explicit norm statement.
• /spdd-reasons-canvas (Norms): specs/safe-output-outcome-evaluation.md Provenance Limits section (lines 29-38) is strong, but the replace_label section (§30) omits an explicit RFC-2119 MUST/SHOULD framing seen in Norms — currently phrased as plain table rows. Done when §30's API failure safeguards use consistent MUST language matching §4 (add_labels) style (already partially present, verify consistency for all 4 items).
• /spdd-reasons-canvas (Structure): specs/security-architecture-spec-summary.md "Spec-to-Lock Sync (v1.0.0)" section references specs/security-architecture-spec-validation.md — confirm the two docs' version numbers and dates stay aligned going forward. Done when both files carry matching "last validated" version markers.
• /spdd-generate: In pkg/workflow/replace_label.go, add/verify a unit test asserting the label-allowlist race condition described above is rejected before the PUT call (ties to the Safeguards gap). Target file: pkg/workflow/replace_label_formal_test.go. Done when a new test case covers "blocked label added via replace_label mid-allowlist-change" and passes under go test ./pkg/workflow/....
• /spdd-generate: Update specs/security-architecture-spec-summary.md §"Implementation Files" to reference the current split-out files (e.g. pkg/workflow/compiler_safe_outputs.go, pkg/workflow/safe_jobs.go, plus whichever file now owns input sanitization/output config logic — confirm via grep -rl "sanitiz" pkg/workflow/*.go). Done when the list matches real file paths, verified by ls each entry.
• /spdd-sync: Add a "Related Specs" cross-reference from specs/safe-output-outcome-evaluation.md §30 to specs/replace-label-spec.md §7 (Error Handling) so error-code semantics (404/5xx/429) stay in lockstep if either spec's retry policy changes. Done when both files link to each other under a Sync/References section.
• /spdd-sync: Create or update a tracking checklist item in specs/safe-outputs-scratchpad-removal.md confirming doc-site navigation and internal links have been swept for the deprecated scratchpad path ahead of the 2026-09-21 deadline. Done when a grep -r "scratchpad/safe-outputs-specification.md" across docs/, .github/ returns zero non-removal-notice matches.

Per-Spec Findings

specs/replace-label-spec.md (806 lines)

• Well-structured W3C-style spec with clear Data Model, Processing Model, REST Interface, Error Handling, Security Considerations, and Compliance Testing sections (10 sections total, ToC accurate).
• Security section (§8) covers label allowlist enforcement, cross-repo restrictions, token scope, and staged mode — solid Safeguards coverage.
• Gap: no explicit norm for a race between allowlist validation and the atomic PUT call if the allowlist changes mid-execution (rare but real TOCTOU-style concern given the atomic REST call design).
• Compliance Testing (§9) has a full checklist (§9.3) — good Operations coverage.

specs/safe-output-outcome-evaluation.md (1058 lines)

• Comprehensive: 30 safe-output type sections (create_pull_request through replace_label), each with Question/API/Evaluation table/OTel attributes/failure safeguards — strong Requirements and Operations structure.
• replace_label (§30) is fully implemented: pkg/cli/outcome_eval.go registers evalReplaceLabel, and the conformance test table (bottom of doc) includes a replace_label row with pass/fail conditions.
• Norms section is present and RFC-2119-compliant at the top level, but per-type sections (like §30) use plain declarative MUST statements without a unifying reference back to the top-level Norms section — minor structural weakness, not a defect.
• Sync Follow-ups sections (Section-to-Test Mapping, Section-to-Implementation Mapping) already exist — good existing sync practice to model other specs after.

specs/safe-outputs-scratchpad-removal.md (9 lines)

• Minimal checklist file. Deadline 2026-09-21 (~4 weeks from this run) to remove scratchpad/safe-outputs-specification.md in favor of the canonical docs/src/content/docs/specs/safe-outputs-specification.md.
• No evidence in-repo of a linked tracking issue or automated check enforcing the deadline — flagged as P1 above.

specs/security-architecture-spec-summary.md (396 lines)

• Good high-level summary of the security architecture: conformance classes, 7-layer defense-in-depth, 7 security guarantees (SG-01–SG-07), formal model references (TLA+, F*, Z3/SMT-LIB).
• Defect found: "Implementation Files" section (lines 312-320) lists pkg/workflow/safe_inputs_parser.go and pkg/workflow/safe_outputs_config.go — neither file exists in the current repo (verified via ls). The other four listed files (engine.go, compiler_safe_outputs.go, safe_jobs.go, compiler_types.go) do exist. This is a stale-reference defect from refactoring — flagged as P0.
• "Spec-to-Lock Sync (v1.0.0)" section ties this summary to specs/security-architecture-spec-validation.md — good existing sync convention.

specs/security-architecture-spec-validation.md (755 lines)

• Companion validation doc to the security architecture spec; ties directly to the summary's "Spec-to-Lock Sync" section above.
• Recommend periodic version/date alignment checks between this file and the summary (see Structure checklist item above).

Sync Follow-ups

• Fix stale file references in specs/security-architecture-spec-summary.md and re-verify against pkg/workflow/*.go listing.
• Cross-link specs/safe-output-outcome-evaluation.md §30 and specs/replace-label-spec.md §7 for shared error-handling semantics.
• Add/confirm a tracking mechanism (issue or CI check) for the scratchpad/safe-outputs-specification.md 2026-09-21 removal deadline.
• Keep specs/security-architecture-spec-summary.md and specs/security-architecture-spec-validation.md version markers synchronized on future edits.

Context

• Files reviewed this run (rotation index 10–14 of 19): specs/replace-label-spec.md, specs/safe-output-outcome-evaluation.md, specs/safe-outputs-scratchpad-removal.md, specs/security-architecture-spec-summary.md, specs/security-architecture-spec-validation.md
• Rotation state: advanced to last_index: 15 (next run starts at specs/security-architecture-spec.md), persisted to /tmp/gh-aw/cache-memory/spdd-daily/rotation.json
• Run URL: https://github.com/github/gh-aw/actions/runs/32748483740

Generated by 📋 Daily SPDD Spec Planner · copilot · auto · 32.6 AIC · ⌖ 4.17 AIC · ⊞ 7.3K · ◷

• expires on Aug 27, 2026, 8:12 AM UTC-08:00