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

[github-actions]

Summary

Daily SPDD sweep covering 5 rotation-selected specification files (index 5–9 of 15 tracked spec/scratchpad documents). All five are compliance-fixture-adjacent documents: two are formal compliance-fixture README indices (GitHub MCP access control, replace-label), one is the large Intent Attribution & Agent Governance normative spec, one is its compliance-fixture README companion, and one is the OTel Observability Specification. No blocking defects found, but several REASONS-canvas gaps and drift risks were identified — primarily around escalation-norm enforcement, sync-detection automation, and fixture/spec parity checks that are currently manual.

Priority Work Queue

• P0: Verify the "Escalation norm" in specs/intent-attribution-agent-governance.md (§ Sync Notes, 3-consecutive-CI-run rule) has an actual CI implementation; currently only normative text exists with no linked enforcement code.
• P1: Add missing spec_refs cross-links from specs/otel-observability-spec.md §17.3 Implementation Map to the two compliance README files reviewed today (github-mcp-access-control and replace-label) if applicable overlap exists (e.g., MCP span attributes ↔ MCP access-control fixtures).
• P1: Confirm pkg/workflow/replace_label_formal_test.go closes the documented gap that actions/setup/js/replace_label.cjs does not enforce RL-057/RL-058/RL-059 post-setLabels checks.
• P2: Tighten Norms wording in specs/intent-attribution-agent-governance.md around "fully migrate" definition to reference a machine-checkable condition (e.g., CI lint rule name) rather than prose-only description.
• P2: Add a Safeguards subsection to specs/otel-observability-spec.md mirroring the fail-closed language already present in the intent-attribution spec, since both govern optional-but-critical instrumentation paths.

SPDD Checklist

• /spdd-analysis: Confirm CI enforcement exists for the intent-attribution-agent-governance.md escalation norm (3+ consecutive sync-warning runs → compliance failure + tracking issue). Target: search .github/workflows/ and pkg/cli/ for drift-detection logic; done when a concrete file reference is added to the spec or a gap is filed.
• /spdd-analysis: Audit whether specs/otel-observability-spec.md §16 (Reliability and Failure Handling) cross-references the intent-attribution spec's fail-closed safeguards for consistency. Done when either a cross-reference is added or confirmed unnecessary.
• /spdd-reasons-canvas: Add explicit "Safeguards" section to specs/otel-observability-spec.md covering export failure, partial fan-out failure, and shutdown ordering as fail-closed guarantees (currently scattered across §16.1–16.5 without a consolidated Safeguards heading). Done when a ### Safeguards heading exists summarizing §16 guarantees.
• /spdd-reasons-canvas: Review specs/replace-label-compliance/README.md "Related Test IDs" table for completeness against pkg/workflow/replace_label_formal_test.go — confirm all TestFormal* functions in the Behavioral Coverage Map have a corresponding Test ID entry. Done when parity is confirmed or missing rows are added.
• /spdd-reasons-canvas: Review specs/intent-attribution-compliance/README.md Formal Model for a missing "Structure" note describing how PolicyCompiler output shape maps to CLI outcome reporting fields (objective_value, objective_labels, traced_root_url) referenced in the parent spec's "Current implementation" section. Done when a Structure subsection or note is added.
• /spdd-generate: Implement or verify a CI check in .github/workflows/ (or pkg/cli/) that fails the build after 3 consecutive sync-warning runs per the escalation norm in specs/intent-attribution-agent-governance.md §Sync Notes. Target files: .github/workflows/*.md (workflow source) and pkg/cli/ drift-detection code. Done when a passing/failing test demonstrates the 3-run threshold behavior.
• /spdd-generate: Add the outstanding RL-057/RL-058/RL-059 enforcement to actions/setup/js/replace_label.cjs per the documented gap in specs/replace-label-compliance/README.md (lines 140-143). Done when the JS implementation enforces post-setLabels response checks and the formal-helper-stub note is removed from the README.
• /spdd-sync: After any change to .github/objective-mapping.json schema or .github/intent-policy.json schema, re-verify specs/intent-attribution-agent-governance.md §".github/intent-policy.json Schema" (lines 377–512) stays in sync with actual JSON schema validation code. Done when a sync note or automated schema test is linked.
• /spdd-sync: Re-run coverage parity check for specs/replace-label-compliance/README.md Behavioral Coverage Map against pkg/workflow/replace_label_formal_test.go and pkg/workflow/replace_label_transitions_formal_test.go (last verified 2026-08-03); update the "Coverage parity check" date after next verification. Done when date is bumped and any new predicates are added to the table.
• /spdd-sync: Confirm specs/github-mcp-access-control-compliance/README.md Error Code Reference table (-32001..-32006) stays aligned with pkg/cli/gateway_logs_types.go after any code changes there. Done when a diff review confirms parity or discrepancies are filed as follow-up issues.

Per-Spec Findings

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

• Goals: Provide fixture ground truth for 6 access-control guard predicates (P1–P6) evaluated in a strict order; ensure formal tests and YAML fixtures stay consistent.
• Risks: The evaluation order (tool → repo/role/visibility → integrity) is well-specified, but there's no explicit versioning/changelog for fixture schema changes — a future schema change could silently break TestFormal_FixtureRunner without a migration note.
• Missing/ambiguous: No explicit guidance on what happens if a fixture references an error code not in the reference table (fail test vs. silently pass?).
• REASONS gaps: Structure (fixture versioning) and Norms (schema-change process) are the weakest areas; Requirements, Entities, Approach, Operations, and Safeguards (fail-safe deny on invalid config) are well covered.

specs/intent-attribution-agent-governance.md

• Goals: Define deterministic, fail-closed attribution resolution and execution-policy compilation for AI-driven PR/issue governance; bridge legacy .github/objective-mapping.json to .github/intent-policy.json.
• Risks: The escalation norm (3-consecutive-CI-run rule → compliance failure + tracking issue) is normatively strong but has no visible implementation reference in this pass — high risk of "spec-only" governance that isn't actually enforced.
• Missing/ambiguous: "fully migrate" is defined in prose (all active intent keys defined in intent-policy.json) but lacks a machine-checkable predicate or lint rule name, which will make automated sync-checking hard to implement correctly.
• REASONS gaps: Norms section is strong (RFC 2119 language throughout) but Sync (automated drift detection tooling) is underspecified — it describes desired behavior without naming the implementing component. Safeguards section (fail-closed on missing/malformed policy) is well-articulated.

specs/intent-attribution-compliance/README.md

• Goals: Ground-truth fixture set (3 required scenarios) for attribution resolution and fail-closed policy compilation, formalized via 7 invariants (F1–F7).
• Risks: Low — this is a tight, well-bounded compliance doc. Main risk is fixture drift if pkg/intent.Resolver internals change without updating the F1–F7 invariant descriptions.
• Missing/ambiguous: No explicit link back to the CLI reporting fields (objective_value, objective_labels, traced_root_url) mentioned in the parent governance spec — Structure section could clarify how fixture-level policy output maps to those reporting fields.
• REASONS gaps: Structure (data-shape mapping to CLI output) is the main gap; Requirements, Entities, Approach, Operations, and Norms are all clearly defined via the formal model and coverage map.

specs/otel-observability-spec.md

• Goals: Define a comprehensive, versioned (0.4.0) OTel observability contract spanning configuration, context propagation, trace/span/metric/log contracts, security, reliability, and compliance testing across 19 major sections.
• Risks: Very large surface area (970+ lines, 19 sections) increases risk of internal inconsistency between sections (e.g., §16 Reliability vs §17 Compliance Testing) as the spec evolves through minor version bumps without full-document re-review.
• Missing/ambiguous: No single consolidated "Safeguards" heading — fail-closed/reliability guarantees are spread across §16.1 (Non-Fatal Observability), §16.2 (Retry/Queueing), §16.3 (Partial Fan-Out Failure), §16.4 (Sampling), and §16.5 (Shutdown Ordering) without a unifying summary, unlike the intent-attribution spec's explicit ### Safeguards section.
• REASONS gaps: Safeguards (needs consolidation) and Sync (no explicit "Sync Notes" equivalent tying spec version changes to implementation changelog entries beyond §19 Change Log) are the weakest areas. Structure, Operations, and Norms are comprehensive given the RFC 2119 conformance classes in §2.

specs/replace-label-compliance/README.md

• Goals: Provide normative fixture ground truth (RL-001/002/003) and a 25-predicate formal model (P1–P15, Q1–Q9) for the replace-label safe-output type, including glob semantics, allow/blocklist ordering, and staged-mode behavior.
• Risks: Explicitly documents an open spec/implementation gap — actions/setup/js/replace_label.cjs does not yet enforce RL-057/RL-058/RL-059 post-setLabels checks, currently covered only by a "formal helper stub" in Go tests, not the real JS runtime path. This is a real production risk since the JS action is what actually executes at runtime.
• Missing/ambiguous: The "Coverage parity check" note is dated 2026-08-03 — no indication of an automated recurring check, relying on manual note-taking.
• REASONS gaps: Safeguards (RL-057/058/059 not enforced in production JS code) is the most critical gap. Sync (parity check is manual/dated rather than CI-enforced) is secondary. Requirements, Entities, Approach, Structure, Operations, and Norms are otherwise thoroughly documented.

Sync Follow-ups

• Track whether the intent-attribution escalation norm (3-consecutive-CI-run rule) has matching implementation code; if not found within one more rotation cycle, escalate to a P0 tracking issue per the norm's own self-referential requirement.
• Re-verify replace-label RL-057/RL-058/RL-059 JS enforcement status each rotation until the formal-helper-stub note is removed from specs/replace-label-compliance/README.md.
• On next visit to specs/otel-observability-spec.md, confirm whether a consolidated Safeguards section was added and whether §19 Change Log reflects it.
• When .github/intent-policy.json or .github/objective-mapping.json schemas change, re-diff against specs/intent-attribution-agent-governance.md schema section (lines 377–512).

Context

Files reviewed this run (rotation index 5–9 of 15):

• specs/github-mcp-access-control-compliance/README.md
• specs/intent-attribution-agent-governance.md
• specs/intent-attribution-compliance/README.md
• specs/otel-observability-spec.md
• specs/replace-label-compliance/README.md

Rotation state: advanced from last_index: 5 to last_index: 10, persisted to /tmp/gh-aw/cache-memory/spdd-daily/rotation.json. Full tracked set (15 files) spans specs/*.md, specs/*/README.md, and scratchpad/*specification*.md; next run resumes at index 10 (specs/security-architecture-spec-summary.md onward).

Run: §31024957512

Generated by 📋 Daily SPDD Spec Planner · auto · 32.9 AIC · ⌖ 2.91 AIC · ⊞ 7K · ◷

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