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

[github-actions]

Summary

Daily SPDD review of 5 specification files (rotation index 0–4, next run resumes at index 5 of 17 total). Overall the reviewed specs (awf-config-sources-spec.md + compliance fixtures, compiler-threat-detection-spec.md, forecast-compliance-fixtures/README.md, github-mcp-access-control-compliance/README.md) are unusually mature — normative language, conformance test IDs, and safeguards sections are already present. Gaps found are narrower: stale version-history bloat, a missing explicit "Structure" section for one spec, and a few Norms/Sync clarifications needed to keep drift detection and CTR rule lifecycle fully self-enforcing.

Priority Work Queue

• P0: None — no missing MUST-level safeguards or broken conformance links detected in this batch.
• P1: Add a "Structure" section anchor to awf-config-sources-spec.md; tighten CTR-022/CTR-023 spec-history table (§2) which has grown to 13 rows and duplicates prose across versions.
• P2: Clarify Forecast fixtures README missing-file cross-links; add explicit Sync task for GitHub MCP Access Control compliance fixtures to scratchpad spec version pinning.

SPDD Checklist

• /spdd-generate: Add a ## Structure (or equivalent REASONS "Structure") section to specs/awf-config-sources-spec.md describing directory/file layout relationships between the spec, awf-config-sources-compliance/README.md, and pkg/workflow/awf_config_drift_test.go. Done when a new top-level section exists and is cross-referenced from §3 and the compliance README.
• /spdd-sync: Deduplicate specs/compiler-threat-detection-spec.md §2 (Spec-to-Implementation Sync) history table — collapse repeated boilerplate notes for versions 1.0.8–1.0.14 into a single "baseline" row plus a compact changelog, keeping only rows with unique lock-file impact. Done when the table has ≤6 rows without losing CTR-016/018/019/020/021 traceability.
• /spdd-analysis: Review specs/compiler-threat-detection-spec.md §6.6 Optimizer Failure Safeguards for a missing MUST NOT clause on retrying against a different degraded endpoint after exhausting the 3-attempt backoff (currently only covers the same endpoint). Done when the ambiguity is either resolved as intentional (comment added) or a new sub-bullet is drafted.
• /spdd-generate: Implement/verify a TestDriftRecord_AdditionalPropertiesRejected test in pkg/workflow/awf_config_drift_test.go covering T-DR-005 (no additional properties). Done when go test -run TestDriftRecord ./pkg/workflow/ passes and the test name appears in the compliance README cross-reference.
• /spdd-sync: Update specs/forecast-compliance-fixtures/README.md to add a direct markdown link from each "Available Additional Fixtures" row to its corresponding test ID definition in docs/src/content/docs/specs/forecast-specification.md §12 (currently only test ID text, no links). Done when each of the 4 rows has a working relative link.
• /spdd-generate: Add missing fixture file run_summary_partial_et.json referenced conceptually but absent from specs/forecast-compliance-fixtures/ covering a run with partial (non-zero, non-final) token usage snapshot mid-run. Done when file exists and is registered in the README fixture table with a test ID.
• /spdd-analysis: Cross-check specs/github-mcp-access-control-compliance/README.md Formal Model evaluation order (§4.5.3: tool → repo/role/visibility → integrity) against pkg/workflow/github_mcp_access_control_formal_test.go to confirm TestFormal_FixtureRunner enforces P5-before-P6 ordering as documented. Done when a short verification note or corrective test diff is produced.
• /spdd-sync: Register scratchpad source scratchpad/github-mcp-access-control-specification.md with an explicit version/commit pin in specs/github-mcp-access-control-compliance/README.md header so drift between the scratchpad spec (not yet promoted to specs/) and the compliance fixtures is detectable. Done when a "Spec version pinned at commit <sha>" line is added and validated against current HEAD.
• /spdd-generate: Add a fixture for the P1_ToolAllowed "empty tool name against non-empty list denies" edge case as a standalone YAML fixture file (currently only covered inline in TestFormal_ToolNameFilter, not in the fixture table). Done when a new empty-tool-name-deny.yaml fixture exists and is registered in the Fixture Files table.

Per-Spec Findings

specs/awf-config-sources-spec.md + specs/awf-config-sources-compliance/README.md

Analysis: Well-specified drift detection procedure (§7) with a formal DriftRecord JSON Schema (§3.1) and 10 conformance test IDs (T-DR-001–010) already mapped to pkg/workflow/awf_config_drift_test.go. CR-01–CR-06a define clear MUST-level obligations including SLA escalation with owner assignment logic.

REASONS Canvas:

• Requirements: Strong — CR-01 through CR-06a are explicit and testable.
• Entities: Strong — DriftRecord has a full JSON Schema with field reference table.
• Approach: Strong — §7.2 gives a numbered step-by-step drift detection procedure.
• Structure: Weak — no dedicated section describing how spec/compliance-fixtures/implementation files relate as a directory structure; readers must infer this from scattered references.
• Operations: Adequate — §7.4 references the scheduled workflow but doesn't specify retry/timeout for the gh api calls in §7.3 example.
• Norms: Strong — RFC 2119 keywords used consistently.
• Safeguards: Strong — §8 covers canonical-source-unavailable snapshot fallback with explicit expiry (7 days) and cleanup (14 days) rules.

Risks: The example drift-check script (§7.3) is illustrative only (not tested) — could silently drift from actual implementation behavior without a Sync task tying it to a real script/test.

specs/compiler-threat-detection-spec.md

Analysis: Very mature spec (536 lines) with a full CTR-* rule catalog, daily optimizer maintenance protocol (§6), false-positive suppression lifecycle (§6.4), and a three-stage threat lifecycle (Experimental → Candidate → Normative, §6.5). Version history table in §2 has grown to 13 rows with heavy prose duplication.

REASONS Canvas:

• Requirements: Strong — MUST/SHOULD keywords used precisely throughout.
• Entities: Strong — Rule ID, Threat Class, Detection Condition, Compiler Action, Evidence, Implementation Mapping (§4) form a clear schema.
• Approach: Strong — §6.2 Daily Decision Procedure and §6.3 Daily Output Requirements are concrete.
• Structure: Adequate — sections are well organized but numbering has drift (§4.3.1 nested under §6 heading "Rule Lifecycle Requirements" numbered as if under §5/§4 — minor numbering inconsistency between §5.3 and its subsection §4.3.1).
• Operations: Strong — §6.6 Optimizer Failure Safeguards defines exponential backoff (10s initial, 5min max, 3 attempts) and OPTIMIZER_DEGRADED diagnostics.
• Norms: Weak spot — the version-history table (§2) mixes normative sync requirements with historical changelog data, making it hard to tell which lock-file compatibility notes are still active MUST constraints vs. purely historical.
• Safeguards: Strong — degraded-run handling explicitly prevents false noop reports and PR/spec updates on incomplete data.

Risks: The section numbering bug (§4.3.1 referenced under a "5.3" parent) could confuse automated cross-reference validators; low priority but worth a quick fix.

specs/forecast-compliance-fixtures/README.md

Analysis: Short, functional fixture README. Documents one baseline fixture (run_summary_minimal.json) plus four additional fixtures for edge cases (zero ET, failed, high ET, cancelled). Test IDs map to pkg/cli/forecast_montecarlo_test.go and forecast_test.go.

REASONS Canvas:

• Requirements: Adequate — test ID ranges given but no explicit MUST/SHOULD language (this is a fixtures README, not the normative spec itself, so this is acceptable).
• Entities: Adequate — RunSummary schema fields documented with Go struct cross-references.
• Approach: Adequate — clear go test invocation examples including -race.
• Structure: Adequate — fixture table format is consistent and extensible.
• Operations: Weak — no guidance on what to do if a fixture's expected values drift from the actual RunSummary struct definition (no Sync procedure).
• Norms: N/A for this doc type.
• Safeguards: Missing — no fixture registered for a "partial/in-progress" token usage snapshot, a plausible edge case gap for the Monte Carlo engine.

Risks: Low; primarily coverage gaps rather than correctness issues.

specs/github-mcp-access-control-compliance/README.md

Analysis: Excellent formal model with 6 guard predicates (P1–P6) evaluated in documented order, a full behavioral coverage map linking predicates to test functions, and an error-code reference table. This is one of the strongest READMEs reviewed — includes explicit safety invariants (SAFETY_BlockedUserAlwaysDenied, SAFETY_NoSpuriousAllowInvariant).

REASONS Canvas:

• Requirements: Strong — formal ALLOW(r,c) conjunction defined mathematically.
• Entities: Strong — AccessRequest, ToolConfig, Decision types are explicit.
• Approach: Strong — fixture runner pattern (TestFormal_FixtureRunner) dynamically drives YAML scenarios.
• Structure: Strong — fixture schema (YAML keys) is fully documented.
• Operations: Adequate — "Adding New Fixtures" section gives a clear 5-step process.
• Norms: Adequate — uses MUST for error code contract but doesn't use RFC 2119 boilerplate (defers to parent scratchpad spec, which is acceptable since this is a compliance-fixtures README, not the normative doc).
• Safeguards: Gap — this README depends on scratchpad/github-mcp-access-control-specification.md, which (being in scratchpad/) is not version-pinned; if the scratchpad spec changes without corresponding fixture updates, the fixture runner tests could silently validate against a stale formal model.

Risks: Since the referenced normative spec lives in scratchpad/ rather than specs/, it may not receive the same durability/versioning guarantees — worth flagging for eventual promotion to specs/.

Sync Follow-ups

• Track promotion of scratchpad/github-mcp-access-control-specification.md to specs/ once the formal model stabilizes (it is already referenced by a specs/*compliance/README.md, which is normally the pattern for promoted specs).
• Cross-reference specs/compiler-threat-detection-spec.md §2 version table against the actual CTR rule catalog after each new CTR-* rule addition to prevent the table from silently falling out of sync with binary version requirements.
• Verify specs/awf-config-sources-spec.md §7.3 example drift-check script still matches the real automation entrypoint referenced in §7.4 (schema-consistency-checker.md) — add an automated test or comment noting last-verified date.
• Confirm pkg/workflow/awf_config_drift_test.go implements all 10 T-DR test IDs claimed in the compliance README; if any are missing, open a corrective PR per CR-05 semantics of the parent spec.

Context

• Files reviewed this run (rotation index 0–4 of 17): specs/awf-config-sources-compliance/README.md, specs/awf-config-sources-spec.md, specs/compiler-threat-detection-spec.md, specs/forecast-compliance-fixtures/README.md, specs/github-mcp-access-control-compliance/README.md
• Rotation state: persisted to /tmp/gh-aw/cache-memory/spdd-daily/rotation.json; next run resumes at index 5 (specs/github-mcp-access-control-compliance/README.md was last processed; next file is specs/intent-attribution-agent-governance.md)
• Run URL: workflow-run-id 31510907352 in github/gh-aw
• Date: 2026-08-11

Generated by 📋 Daily SPDD Spec Planner · auto · 30.9 AIC · ⌖ 2.05 AIC · ⊞ 6.8K · ◷

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