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

[github-actions]

Summary

This daily SPDD plan covers 5 specification files reviewed in this run: specs/awf-config-sources-spec.md, specs/compiler-threat-detection-spec.md, specs/otel-observability-spec.md, specs/replace-label-spec.md, and specs/safe-output-outcome-evaluation.md. These specs range from Working Draft to Candidate Recommendation status. The primary gaps identified are: missing implementation validation tests, underspecified error handling in several areas, weak sync procedures, and absent safeguard language for edge cases. 9 actionable tasks are defined below.

Priority Work Queue

P0 (critical / blocks implementation correctness)

• safe-output-outcome-evaluation.md has no section for the replace_label outcome type despite that type being specified in replace-label-spec.md; these two specs are out of sync.
• compiler-threat-detection-spec.md Section 6 (Daily Optimizer Maintenance Protocol) lacks explicit safeguard language for what happens when the optimizer itself fails or is skipped.

P1 (important / spec quality and testability)

• otel-observability-spec.md Section 11 (Metrics Contract) and Section 12 (Logs Contract) need explicit conformance test hooks.
• awf-config-sources-spec.md Section 6 (Drift Detection Procedure, Step 5) defines the DriftRecord entity schema but has no sync notes pointing back to implementation files in pkg/workflow/.
• replace-label-spec.md Section 7 (Error Handling) does not specify what outcome to emit when the GitHub API returns a partial success (200 with fewer labels than expected).

P2 (maintenance / norms and structure)

• awf-config-sources-spec.md has no Entities section — the DriftRecord schema is embedded in the procedure rather than a dedicated Data Model section.
• safe-output-outcome-evaluation.md Norms section uses bare RFC 2119 keywords without anchoring to which conformance target they apply.
• otel-observability-spec.md version 0.4.0 has an Abstract that says implementations MUST NOT remove shipped behavior, but Section 17 (Compliance Testing) does not include a test for backward-compat preservation.
• compiler-threat-detection-spec.md CTR-021 warning says "warn in non-strict mode" but does not define what a non-strict warning record looks like in the diagnostics output schema.

SPDD Checklist

• [/spdd-generate] specs/safe-output-outcome-evaluation.md: Add replace_label outcome type section with accepted/rejected/ignored classification rules and OTel attributes, mirroring the pattern used for create_pull_request. Done when the section exists, covers all 6 outcome categories, and references replace-label-spec.md. Target file: specs/safe-output-outcome-evaluation.md.
• [/spdd-analysis] specs/compiler-threat-detection-spec.md Section 6: Identify missing safeguard language for optimizer-failure scenarios (optimizer job fails, is skipped, or is rate-limited). Done when the section has at least one explicit MUST or SHOULD for each failure mode. Target file: specs/compiler-threat-detection-spec.md.
• [/spdd-generate] specs/compiler-threat-detection-spec.md Section 6: Add a Safeguards subsection specifying behavior when the daily optimizer cannot complete its threat-coverage check (e.g., API unavailability, runner timeout). Reference the pattern used in awf-config-sources-spec.md Section 7. Done when at least 3 failure-mode behaviors are specified. Target file: specs/compiler-threat-detection-spec.md.
• [/spdd-reasons-canvas] specs/otel-observability-spec.md Section 17 (Compliance Testing): Score the section against the REASONS canvas — specifically check for missing Norms (are test pass/fail criteria normative?) and missing Safeguards (what happens if an exporter is unreachable during testing?). Done when a written gap analysis exists for each REASONS dimension. Target file: specs/otel-observability-spec.md.
• [/spdd-generate] specs/otel-observability-spec.md Section 17: Add a backward-compatibility compliance test requirement: a test MUST verify that fields present in v0.3.0 are still present in v0.4.0 export. Done when Section 17 contains at least one test case that references version compatibility. Target file: specs/otel-observability-spec.md.
• [/spdd-generate] specs/awf-config-sources-spec.md: Extract the DriftRecord JSON schema (currently embedded in Section 6.5) into a dedicated Section 3: Data Model (Entities). Done when a standalone Data Model section exists and Section 6.5 cross-references it. Target file: specs/awf-config-sources-spec.md.
• [/spdd-sync] specs/awf-config-sources-spec.md Section 6.5 (DriftRecord): Add sync notes mapping each DriftRecord field to the implementation file that produces it in pkg/workflow/. Done when each required field (property_path, drift_category, suggested_action, detected_at) has a target file reference. Target file: specs/awf-config-sources-spec.md.
• [/spdd-generate] specs/replace-label-spec.md Section 7 (Error Handling): Add an explicit handling rule for partial-success responses (HTTP 200 but returned label set does not match the expected post-operation set). Specify whether this should produce rejected or a new error code. Done when the section addresses the partial-success case with a MUST-level requirement. Target file: specs/replace-label-spec.md.
• [/spdd-analysis] specs/safe-output-outcome-evaluation.md Norms section: Tighten RFC 2119 usage by specifying the conformance target (outcome evaluation workers) for each keyword instance. Done when each MUST/MUST NOT/SHOULD statement explicitly names its conformance target. Target file: specs/safe-output-outcome-evaluation.md.

Per-Spec Findings

specs/awf-config-sources-spec.md — AWF Config Canonical Sources Spec (v0.1.0, Working Draft)

SPDD Analysis:

• Goals: Define canonical source files in gh-aw-firewall that agents must consult for AWF config validation.
• Risks: Spec drift between JSON schemas and normative spec; no freshness timestamp on the canonical source list.
• Missing constraints: No freshness/staleness rule for the canonical sources list itself (Section 2); if gh-aw-firewall renames a file, nothing in this spec triggers an update obligation.
• Ambiguous requirements: CR-06a says "default escalation owner SHOULD be determined via git log" — this is advisory for an automated system but undefined for a human fallback when git log is inconclusive.

REASONS Canvas gaps:

• Entities: DriftRecord schema exists (§6.5) but is not in a dedicated entities section.
• Approach: §6.2 procedure is well-specified.
• Structure: Well-structured.
• Operations: §6.2 step sequence is complete.
• Norms: CR-06 SLA (5 business days) is present. CR-06a escalation assignment logic is advisory, not MUST.
• Safeguards: §7 is present and covers unavailability scenarios.

specs/compiler-threat-detection-spec.md — Compiler Threat Detection Spec (v1.0.18, Candidate Recommendation)

SPDD Analysis:

• Goals: Define 21 compiler threat-detection rules (CTR-001 through CTR-021).
• Risks: Section 6 (Daily Optimizer) is under-specified for failure modes; if the optimizer is skipped, no spec obligation prevents silent regression.
• Missing constraints: CTR-021 warning diagnostic format is not defined; "warn" is used without referencing the diagnostic output schema.
• Ambiguous requirements: "Daily Optimizer Maintenance Protocol" (§6) title implies a daily cadence, but §6 body may not enforce it with MUST.

REASONS Canvas gaps:

• Requirements: 21 rules are well-specified.
• Entities: Rule model (§4) is defined.
• Approach: Compiler-first, spec-driven.
• Structure: Well-organized.
• Operations: §6 (Daily Optimizer) lacks failure-mode safeguards.
• Norms: Present in §3.
• Safeguards: Missing from §6 — no behavior spec when the optimizer cannot complete.

specs/otel-observability-spec.md — OTel Observability Spec (v0.4.0, Working Draft)

SPDD Analysis:

• Goals: Define compatibility-first OTel contract for gh-aw traces, metrics, logs, OTLP export.
• Risks: Abstract states MUST NOT remove v0.3.0 behavior, but Section 17 has no test enforcing this.
• Missing constraints: Section 17 (Compliance Testing) does not include a backward-compat test.
• Ambiguous requirements: "additive evolution" in the abstract is not precisely defined — what constitutes an additive change vs. a breaking one?

REASONS Canvas gaps:

• Requirements: Well-specified.
• Entities: Span/metric/log models defined.
• Approach: Compatibility-first is stated.
• Structure: Large but well-organized (19 sections).
• Operations: Export operations specified.
• Norms: Present.
• Safeguards: §16 covers reliability. §17 missing backward-compat test.

specs/replace-label-spec.md — replace-label Safe-Output Type Spec (v1.0.0, Candidate Recommendation)

SPDD Analysis:

• Goals: Define replace-label safe-output type with atomic label-set replacement.
• Risks: Section 7 (Error Handling) does not specify partial-success case.
• Missing constraints: No handling rule when GitHub API 200 response returns fewer labels than the expected post-operation set.
• Ambiguous requirements: "single REST API call" atomicity claim needs a test case in §9 to verify it.

REASONS Canvas gaps:

• Requirements: Well-specified.
• Entities: Data model (§4) present.
• Approach: Atomic PUT approach specified.
• Structure: Complete (12 sections).
• Operations: §5 Processing Model is thorough.
• Norms: §2 and §8 present.
• Safeguards: §7 missing partial-success case.

specs/safe-output-outcome-evaluation.md — Safe Output Outcome Evaluation Spec (v1.0.0, Working Draft)

SPDD Analysis:

• Goals: Define outcome evaluation logic (accepted/rejected/ignored/pending/lifecycle) for each safe-output type.
• Risks: replace_label outcome type is absent despite being a shipped type.
• Missing constraints: No outcome definition for replace_label; norms section does not name conformance targets per keyword.
• Ambiguous requirements: "time-bounded" check at 48h default — no MUST on what happens if the evaluation system is offline for >48h.

REASONS Canvas gaps:

• Requirements: Most types covered, replace_label missing.
• Entities: Outcome categories defined.
• Approach: Observer-based evaluation stated.
• Structure: Compact; outcome type coverage could be in a table.
• Operations: Missing replace_label operation.
• Norms: Present but conformance target not named per statement.
• Safeguards: API failure handling is specified (§Norms 1-4); offline evaluation window not covered.

Sync Follow-ups

• After adding replace_label outcome section to safe-output-outcome-evaluation.md, verify cross-reference from replace-label-spec.md §9 (Compliance Testing) points to the evaluation spec.
• After extracting DriftRecord into a Data Model section in awf-config-sources-spec.md, update all internal cross-references from §6.5 to the new section number.
• After adding optimizer safeguards to compiler-threat-detection-spec.md §6, check that the daily optimizer workflow file (.github/workflows/) references the new failure-mode behavior in its failure step.
• After adding backward-compat test to otel-observability-spec.md §17, check that the compliance test harness (if any) in pkg/ has a corresponding test stub.

Context

Files reviewed this run (5):

• specs/awf-config-sources-spec.md (v0.1.0, Working Draft)
• specs/compiler-threat-detection-spec.md (v1.0.18, Candidate Recommendation)
• specs/otel-observability-spec.md (v0.4.0, Working Draft)
• specs/replace-label-spec.md (v1.0.0, Candidate Recommendation)
• specs/safe-output-outcome-evaluation.md (v1.0.0, Working Draft)

Rotation index: 55–59 of 727 total files

References:

• §30285401453

Generated by 📋 Daily SPDD Spec Planner · sonnet46 · 31.8 AIC · ⌖ 6 AIC · ⊞ 4.9K · ◷

• expires on Jul 30, 2026, 8:42 AM UTC-08:00