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

[github-actions]

Summary

This daily SPDD plan covers 5 reference documentation files reviewed at rotation index 34–38: cost-management, markdown, qmd, measuring-impact, and glossary. The documents are generally well-structured but share common gaps across REASONS canvas dimensions — particularly missing Norms (normative RFC 2119 language), weak Safeguards (failure-mode coverage), underspecified Operations ordering, and incomplete Sync hooks. Today's tasks focus on tightening normative language, filling safeguard gaps, and improving cross-document sync anchors.

Priority Work Queue

Priority	Area	File
P0	Add safeguard section for AIC computation failures	docs/src/content/docs/reference/cost-management.md
P0	Tighten normative language (MUST/SHOULD/MAY) in markdown scanner rules	docs/src/content/docs/reference/markdown.md
P1	Add norms around qmd index staleness and cache-key rotation	docs/src/content/docs/reference/qmd.md
P1	Specify done-conditions for impact metrics	docs/src/content/docs/reference/measuring-impact.md
P2	Expand glossary Ops pattern entries with cross-links to spec files	docs/src/content/docs/reference/glossary.md

SPDD Checklist

• [/spdd-analysis → cost-management] Identify missing constraint: specify what MUST happen when AIC pricing data is unavailable or stale (models.dev unreachable). Target: cost-management.md. Done when a "Failure Modes" or "Safeguards" subsection documents fallback behavior.
• [/spdd-generate → cost-management] Add a ## Safeguards or ## Error Handling section covering: AIC estimation failure fallback, gh aw logs unavailability, and what to do when OTLP endpoint is unreachable. Done when section exists with ≥3 failure modes.
• [/spdd-reasons-canvas → markdown] Audit the markdown scanner rules section for normative language gaps. Replace informal prose ("the scanner rejects", "these checks cannot be overridden") with RFC 2119 MUST/MUST NOT statements. Done when scanner rules use at least 5 normative keywords.
• [/spdd-generate → markdown] Add a ## Norms or ## Constraints subsection that enumerates: which scanner checks are compile-time vs runtime, what happens when a check fires (error vs warning), and whether any checks are configurable. Done when the subsection explicitly states the enforcement point for each check category.
• [/spdd-analysis → qmd] Document what happens when the qmd cache key is missing or expired at agent job startup. The current spec says the agent operates in "read-only mode" but does not say what happens when the cache is absent. Done when a failure-mode paragraph describes the missing-cache behavior.
• [/spdd-reasons-canvas → qmd] Add a ## Norms subsection specifying: how often the cache-key SHOULD be rotated (per-run vs per-PR vs weekly), whether stale indexes are accepted or rejected, and the expected latency SLA for index builds. Done when norms subsection has ≥3 normative statements.
• [/spdd-generate → measuring-impact] The "Practical Measurement Model" section lists metrics but lacks done-conditions. Add explicit success thresholds or at least a normative statement that teams SHOULD define acceptance thresholds before deploying a workflow. Done when at least one metric has a reference threshold or normative adoption criterion.
• [/spdd-sync → measuring-impact] Add a sync note linking to cost-management.md for the cost side and outcomes.md for the acceptance side — the prose references both but the cross-doc sync anchors are missing. Done when both cross-references include the correct relative path and are validated by make recompile.
• [/spdd-reasons-canvas → glossary] The glossary Ops pattern entries (e.g. SpecOps, CorrectionOps, WorkQueueOps) link to pattern pages but not to spec files. Add spec cross-links where a formal spec exists. Done when ≥3 glossary entries include a "See also: spec" reference.
• [/spdd-sync → glossary] Audit the glossary for terms defined in specs/**/*.md that are not yet in the glossary. Add at minimum: "Intent Attribution", "Safe Output Outcome Evaluation", and "AWF Config Sources". Done when each new term has a ≥2-sentence definition with a link to its spec file.

Per-Spec Findings

cost-management.md

Analysis: Well-structured with clear cost components, monitoring commands, and OTLP guidance.

REASONS gaps:

• Safeguards: No section covering what happens when AIC pricing data is unavailable, when gh aw logs returns an error, or when the OTLP endpoint is unreachable.
• Norms: AIC is described as "best-effort" but there are no normative statements about what accuracy tolerance is acceptable.
• Operations: Steps for tracking cost at scale are described narratively; no ordered operation sequence.

Generate tasks: Add Safeguards section with ≥3 failure modes. Add normative accuracy tolerance statement for AIC.

markdown.md

Analysis: Covers markdown body authoring, scanning, sub-agents, and temp file paths well.

REASONS gaps:

• Norms: Scanner rules use informal language. RFC 2119 normative keywords would make enforcement intent unambiguous.
• Structure: Scanner check categories are listed as prose but not as a structured table, making it hard to reference individual checks.
• Safeguards: What happens if a workflow bypasses the scanner at import time is unspecified.

Generate tasks: Normalize scanner rules to RFC 2119; add structured table of scanner checks with enforcement point column.

qmd.md

Analysis: Good coverage of configuration options. The cache-key and read-only mode sections are present but underspecified.

REASONS gaps:

• Norms: No normative guidance on cache-key rotation frequency or staleness policy.
• Safeguards: Missing-cache behavior at agent startup is not defined.
• Entities: The stats.json and queries.jsonl artifacts are described only in the telemetry example, not as first-class entities.

Generate tasks: Add Norms subsection; document missing-cache behavior; promote qmd artifact paths to an "Artifacts" subsection.

measuring-impact.md

Analysis: Thoughtful layered metrics model. Correctly avoids synthetic scores.

REASONS gaps:

• Norms: No thresholds or normative adoption criteria. "Useful output rate moving up" is directional but not actionable.
• Operations: The order of measurement steps (instrument → baseline → iterate) is implied but not stated.
• Sync: Cross-doc references to cost-management.md and outcomes.md are prose-only; no structured sync anchors.

Generate tasks: Add at least one reference threshold per metric tier; add sync anchors to related docs.

glossary.md

Analysis: Comprehensive Ops pattern coverage. Core concepts section is solid.

REASONS gaps:

• Entities: Several spec-defined entities (Intent Attribution, AWF Config Sources, Safe Output Outcome Evaluation) are absent from the glossary.
• Sync: Ops pattern entries link to guide pages but not to formal specs where they exist.
• Norms: No stated policy for when a term MUST be added to the glossary.

Generate tasks: Add 3 missing spec-derived terms; add spec cross-links to ≥3 Ops entries; document glossary contribution norm.

Sync Follow-ups

• After updating markdown.md scanner rules with RFC 2119 language, verify the compiler threat-detection spec (specs/compiler-threat-detection-spec.md) uses the same terminology and open a follow-up task if they diverge.
• After adding the qmd missing-cache behavior, check docs/src/content/docs/reference/cache-memory.md for consistency and add a cross-reference.
• After adding glossary entries for spec-defined terms, run a grep for each new term across specs/**/*.md to confirm the definition matches the spec usage.
• After measuring-impact sync anchors are added, validate with make recompile to catch broken relative links.

Context

Field	Value
Files reviewed	cost-management.md, markdown.md, qmd.md, measuring-impact.md, glossary.md
Rotation index (start)	34
Rotation index (end)	39
Total files tracked	680
Run	§29759033509

References:

• §29759033509

Generated by 📋 Daily SPDD Spec Planner · 33.2 AIC · ⌖ 5.34 AIC · ⊞ 4.8K · ◷

• expires on Jul 23, 2026, 8:24 AM UTC-08:00