Close SPDD gaps for forecast discovery, frontmatter hash limits, and related specs

[Copilot]

This PR addresses the May 13 SPDD review items across the forecast, frontmatter-hash, effective-tokens, experiments, and fuzzy-schedule specs. The main code changes close the two sync gaps called out in the plan: forecast discovery now degrades predictably under GitHub API rate limiting, and frontmatter hashing now enforces the 1 MiB safeguard at runtime.

• Forecast: rate-limit backoff + partial discovery

  • Add bounded retry/backoff for remote workflow discovery and run sampling in pkg/cli/forecast.go
  • Continue with caller-supplied workflow IDs as partial results when remote discovery is rate-limited after retries
  • Surface degraded-discovery behavior as warnings instead of hard-failing the entire forecast path

  if len(ids) > 0 {
  	fmt.Fprintln(os.Stderr, console.FormatWarningMessage(
  		fmt.Sprintf("GitHub API rate limit exhausted while discovering workflows in %s; continuing with caller-supplied workflow IDs as partial results",
  			repoOverride)))
  
  	partialWorkflows := make(map[string]*GitHubWorkflow, len(ids))
  	for _, id := range ids {
  		partialWorkflows[id] = &GitHubWorkflow{Name: id, Path: id, State: "unknown"}
  	}
  	return partialWorkflows, nil
  }

• Frontmatter hash: enforce S-6 at runtime

  • Add a normalized-input size guard in pkg/parser/frontmatter_hash.go
  • Reject cumulative normalized frontmatter input above 1 MiB with a deterministic error
  • Add a focused compliance test in pkg/parser/frontmatter_hash_test.go

• Forecast specification alignment

  • Add remote discovery rate-limit requirements and partial-result behavior
  • Add T-FC-030 coverage for rate-limit fallback
  • Add the missing historical sample staleness requirement and --max-age spec entry

• Spec maintenance updates

  • Effective Tokens: define overflow ceiling/flagging behavior and clarify partial aggregation ordering for deeper sub-agent graphs
  • Experiments: attach Draft→CR promotion criteria to an explicit tracking issue
  • Frontmatter Hash: replace prose-only v2 migration prerequisites with tracked checklist items
  • Fuzzy Schedule: add the calendar output schema section and a concise v1.2.0 change summary

[Copilot]

Pull request overview

This PR updates forecast rate-limit handling, enforces a frontmatter hash input-size guard in Go, and aligns several reference specifications with recent SPDD review items.

Changes:

• Added retry/backoff wrappers for forecast workflow discovery and run sampling.
• Added a 1 MiB normalized frontmatter hash input limit and a focused test.
• Updated reference specs for forecast, frontmatter hash migration tracking, effective tokens, experiments, and fuzzy schedule calendar output.

Show a summary per file

File	Description
pkg/parser/frontmatter_hash.go	Adds normalized frontmatter input-size validation before hashing.
pkg/parser/frontmatter_hash_test.go	Adds a test for oversized frontmatter hash input rejection.
pkg/cli/forecast.go	Adds rate-limit retry/backoff wrappers for workflow discovery and run sampling.
pkg/cli/forecast_montecarlo_test.go	Adds coverage for remote workflow discovery fallback under rate limiting.
docs/src/content/docs/reference/fuzzy-schedule-specification.md	Documents calendar heatmap output schema and v1.2.0 draft notes.
docs/src/content/docs/reference/frontmatter-hash-specification.md	Converts v2 migration prerequisites into tracked checklist items.
docs/src/content/docs/reference/forecast-specification.md	Adds rate-limit fallback requirements, --max-age spec text, and test ID updates.
docs/src/content/docs/reference/experiments-specification.md	Adds tracking issue references to Draft→CR promotion criteria.
docs/src/content/docs/reference/effective-tokens-specification.md	Adds deeper sub-agent aggregation ordering and overflow flagging requirements.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 9/9 changed files
• Comments generated: 5