SPDD: close spec drift gaps across Effective Tokens, Forecast, Frontmatter Hash, Fuzzy Schedule, and MCP Scripts

[Copilot]

This SPDD cycle identified recurring spec-maintenance gaps: missing/insufficient spec↔implementation sync mapping, safeguard sections that were hard to cross-reference, and a few ambiguous or underspecified norms. This PR tightens those areas across five reference specs with targeted, non-behavioral documentation updates.

• Effective Tokens spec (effective-tokens-specification.md)

  • Added structured safeguard entries (S-1..S-3) with explicit threat/mitigation mapping for overflow/capping, non-finite numeric rejection, and registry-validation failure handling.
  • Added an ET test-vectors appendix with labeled baseline and multi-node graph cases plus expected ET totals.
  • Expanded Sync Notes with a §7.1 OTel attribute row-to-code mapping table (attribute key → implementation field/function path).

• Forecast spec (forecast-specification.md)

  • Clarified §3.9 Yield with an explicit formula walkthrough and numeric example.
  • Moved safeguard content from Appendix F into main-body §10.7 (Threat Model, Required Mitigations, Residual Risk), and left Appendix F as a forward reference.
  • Added command-interface cross-reference to safeguards and strengthened Sync Notes mapping for §4.5/§6/§7 implementation ownership.

• Frontmatter Hash spec (frontmatter-hash-specification.md)

  • Added Caller Operations under Implementation Notes describing normative invocation flow for pkg/cli/hash_command.go.
  • Made S-6 concrete by specifying a hard max cumulative normalized frontmatter size: 1,048,576 bytes (1 MiB), with explicit rejection behavior.
  • Added negative vector FH-TV-NEG-001 for oversized-input rejection expectations.

• MCP Scripts spec (mcp-scripts-specification.md)

  • Added a §4.7 sync note documenting current SM-IS-01 enforcement status: required-field validation exists, but explicit per-string 10KB enforcement is not yet implemented in the cited runtime path.
  • Added a Security Marker Sync Map for SM-JS-01, SM-IS-01, and SM-03 linking each marker to implementation files/functions.

• Fuzzy Schedule spec (fuzzy-schedule-specification.md)

  • Extended Sync Notes to explicitly map §3.1 grammar and §6 scattering algorithm to concrete parser/scatter implementation targets.

Example (new style used across updates):

#### S-1: Overflow and Capping
**Threat**: Unbounded multi-invocation ET aggregation can exceed numeric interoperability limits.
**Mitigation**: Enforce JS-safe ceiling, cap deterministically, and emit overflow flag/error metadata.
Normative requirements: **R-SAFE-002**, **R-SAFE-003**, **R-SAFE-003A**, **R-SAFE-004**

[Copilot]

Pull request overview

Documentation-only SPDD update that tightens spec↔implementation synchronization by adding clearer safeguard sections, concrete test vectors, and explicit “sync notes” mappings across several reference specifications.

Changes:

• Expanded safeguards/threat-model sections and clarified formulas/examples (ET + Forecast).
• Added/extended sync maps from spec sections/markers to concrete implementation files/functions (ET, Forecast, MCP Scripts, Fuzzy Schedule).
• Made Frontmatter Hash limits and negative test vectors more concrete (1 MiB cap, oversized-input rejection vector).

Show a summary per file

File	Description
docs/src/content/docs/reference/mcp-scripts-specification.md	Adds sync note on SM-IS-01 enforcement status and a security marker sync map.
docs/src/content/docs/reference/fuzzy-schedule-specification.md	Adds explicit sync-note mappings for grammar and scattering algorithm.
docs/src/content/docs/reference/frontmatter-hash-specification.md	Adds caller-operation requirements plus a concrete 1 MiB limit and oversized-input negative vector.
docs/src/content/docs/reference/forecast-specification.md	Adds yield example, moves safeguards into main body, and strengthens sync notes mapping.
docs/src/content/docs/reference/effective-tokens-specification.md	Adds structured safeguards, ET test vectors appendix, and an OTel attribute→code mapping table.

Copilot's findings

Tip

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

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