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

### Summary

This plan covers 5 specification documents reviewed on 2026-05-24 (rotation indices 0–4, first run / cache miss — initialized from start). Key findings: weak safeguard norms in MCP Scripts, open sync follow-ups in Forecast, four open v2.0.0 migration gates in Frontmatter Hash, and missing end-to-end schedule integration test coverage in Fuzzy Schedule.

### Priority Work Queue

| Priority | Task | Spec |
|----------|------|------|
| P0 | Add Sync Notes section to `effective-tokens-specification.md` (no impl-file mapping exists) | Effective Tokens |
| P0 | Upgrade MCP Scripts §7.3 input length limit from SHOULD to MUST norm | MCP Scripts |
| P1 | Add fixture tests for invalid/non-finite λ and zero-projection fallback in `forecast_montecarlo_test.go` | Forecast |
| P1 | Add integration test assertions for `compile_schedule_calendar.go` output in fuzzy-schedule changes | Fuzzy Schedule |
| P1 | Strengthen MCP Scripts §7.2 JS-tool isolation: change SHOULD to MUST for sandbox requirements | MCP Scripts |
| P2 | Add assertion in `forecast.go` / `forecast_command.go` ensuring verbose diagnostics and JSON output share same λ value | Forecast |
| P2 | Clarify §9 Extensibility in Effective Tokens: add normative MUST NOT extension rules and reference `pkg/cli/forecast_montecarlo.go` | Effective Tokens |
| P2 | Track v2.0.0 frontmatter hash migration prereqs — verify all 4 checklist items in issue `#31983` are assigned | Frontmatter Hash |

### SPDD Checklist

- [ ] `/spdd-generate` · Add `## Sync Notes` section to `docs/src/content/docs/reference/effective-tokens-specification.md` mapping §4–§8 to `pkg/cli/forecast_montecarlo.go`, `pkg/otel/`, and any ET reporter files. Done when section includes a file-mapping table and a sync procedure list.
- [ ] `/spdd-generate` · In `docs/src/content/docs/reference/mcp-scripts-specification.md` §7.3, change "SHOULD be at least 10KB" to "MUST enforce a maximum input string length of at least 10KB" and add a normative requirement ID (e.g., `SM-03`). Done when the requirement uses RFC-2119 MUST and has an ID.
- [ ] `/spdd-generate` · In `docs/src/content/docs/reference/mcp-scripts-specification.md` §7.2, add a normative `SM-02` requirement: "JavaScript tools MUST execute in a sandboxed V8 context with restricted global scope." Done when SHOULD → MUST and requirement ID is added.
- [ ] `/spdd-generate` · In `pkg/cli/forecast_montecarlo_test.go`, add table-driven test cases for: (a) non-finite λ input (NaN, +Inf), (b) λ = 0 zero-projection fallback. Done when `go test ./pkg/cli/ -run TestMonteCarlo` passes with new cases.
- [ ] `/spdd-sync` · Update `docs/src/content/docs/reference/forecast-specification.md` §13 sync follow-ups: move inline TODO bullets into tracked GitHub issues (or link to existing ones). Done when each follow-up references an issue number.
- [ ] `/spdd-generate` · In `pkg/parser/schedule_fuzzy_scatter_test.go` or `pkg/cli/compile_schedule_calendar_test.go`, add at least one end-to-end test that exercises a fuzzy schedule expression through `compile_schedule_calendar.go` and asserts on generated cron output. Done when `go test -run TestFuzzyScheduleEndToEnd` (or equivalent) passes.
- [ ] `/spdd-analysis` · Review `docs/src/content/docs/reference/effective-tokens-specification.md` §9 Extensibility: add at least one MUST NOT normative constraint (e.g., "extensions MUST NOT redefine default weight values without a version bump"). Done when §9 contains at least one MUST/MUST NOT requirement.
- [ ] `/spdd-sync` · Verify all 4 open checklist items in frontmatter hash spec §Future Versions are tracked and assigned in issue `#31983`. Done when each item has an assignee or a linked sub-issue.

### Per-Spec Findings

<details>
<summary>effective-tokens-specification.md (v0.2.0, Draft)</summary>

#### /spdd-analysis
- **Goals**: Define a normalized LLM token metric (ET) across classes, weights, and multi-agent graphs.
- **Risks**: No sync notes → drift between spec and implementation undetected. Overflow safeguards present but no compliance tests.
- **Missing constraints**: §9 Extensibility has no MUST/MUST NOT rules — only permissive MAY bullets.
- **Ambiguities**: No reference to which implementation files are authoritative for ET computation.

#### /spdd-reasons-canvas
| Area | Strength | Gap |
|------|----------|-----|
| Requirements | Strong (RFC-2119, §8) | §9 lacks normative extension constraints |
| Entities | Good (§3 terminology, §6 node schema) | — |
| Approach | Good (formula, aggregation) | — |
| Structure | Good (ToC, sections) | — |
| Operations | Adequate | No operations ordering for overflow detection |
| Norms | Good (R-SAFE-001–003A) | SHOULD vs MUST inconsistency in §8.4 partial visibility |
| Safeguards | Present | No compliance test vectors for overflow/ceiling |

**Sync Notes**: ❌ Missing entirely — no file mapping table.

</details>

<details>
<summary>forecast-specification.md (v0.1.0, Experimental Draft)</summary>

#### /spdd-analysis
- **Goals**: Specify `gh aw forecast` Monte Carlo projection of ET usage.
- **Risks**: 3 open sync follow-up TODOs not tracked in issues. λ/verbose diagnostic alignment unverified.
- **Missing constraints**: No normative requirement that JSON and verbose output use the same λ.
- **Ambiguities**: Zero-projection fallback behavior underspecified in §7.5.

#### /spdd-reasons-canvas
| Area | Strength | Gap |
|------|----------|-----|
| Requirements | Detailed (R-MC-* IDs) | λ=0 and non-finite λ paths underdefined |
| Entities | Good (§3) | — |
| Approach | Strong (Poisson+Bootstrap+Bernoulli) | — |
| Structure | Good | — |
| Operations | Good (§6 sampling procedure) | — |
| Norms | Good | JSON/verbose output λ coupling not normative |
| Safeguards | Present (§10.6, Appendix F) | No test vectors for non-finite λ |

**Sync Notes**: ✅ Present with 3 open follow-up TODOs (untracked).

</details>

<details>
<summary>frontmatter-hash-specification.md (v1.0.0, Draft)</summary>

#### /spdd-analysis
- **Goals**: Deterministic hash of workflow frontmatter for stale-lock detection.
- **Risks**: v2.0.0 migration has 4 open blocking prerequisites gated on issue `#31983`. Cross-language divergence risk (Go vs JS).
- **Missing constraints**: None critical for v1.0.0.
- **Ambiguities**: BFS diamond-import tie-breaking is specified but not covered by a dedicated test vector in Appendix A.

#### /spdd-reasons-canvas
| Area | Strength | Gap |
|------|----------|-----|
| Requirements | Strong | — |
| Entities | Good | — |
| Approach | Strong (text-based) | v2.0.0 field-selection model not yet designed |
| Structure | Good | — |
| Operations | Strong (sync procedure §Sync Notes) | — |
| Norms | Good (S-1–S-6) | — |
| Safeguards | Strong | Diamond-import BFS test vector missing |

**Sync Notes**: ✅ Well-defined. 4 v2.0.0 gate checklist items open.

</details>

<details>
<summary>fuzzy-schedule-specification.md (v1.2.0, Draft)</summary>

#### /spdd-analysis
- **Goals**: Human-friendly scheduling DSL → cron expressions with deterministic scatter.
- **Risks**: Sync notes recommend end-to-end compile coverage for calendar changes but no existing E2E test.
- **Missing constraints**: No normative requirement for compile-path integration tests.
- **Ambiguities**: §6.4.2 peak-minutes avoidance does not specify behavior when `avoidPeakMinutes` set is empty.

#### /spdd-reasons-canvas
| Area | Strength | Gap |
|------|----------|-----|
| Requirements | Strong (grammar, R-SCHED-*) | — |
| Entities | Good | — |
| Approach | Strong (FNV-1a, scattering) | — |
| Structure | Good | — |
| Operations | Good | Calendar E2E path not tested |
| Norms | Good | §6.4.2 empty avoidance set behavior unspecified |
| Safeguards | Adequate | — |

**Sync Notes**: ✅ Present with integration coverage notes.

</details>

<details>
<summary>mcp-scripts-specification.md (v1.1.0, Draft)</summary>

#### /spdd-analysis
- **Goals**: Specify custom MCP tools defined in workflow frontmatter (JS/shell/Python/Go).
- **Risks**: JS tool isolation uses SHOULD (not MUST) for sandboxing; input length limit is also SHOULD. Both weaken security guarantees.
- **Missing constraints**: §7.2 JS isolation and §7.3 input length must be upgraded to MUST.
- **Ambiguities**: §6.4 Go tools require a separate container image — no normative requirement for fallback or error when image is unavailable.

#### /spdd-reasons-canvas
| Area | Strength | Gap |
|------|----------|-----|
| Requirements | Strong | §7.2 SHOULD → MUST for JS sandbox |
| Entities | Good | — |
| Approach | Strong | Go tool container unavailability not covered |
| Structure | Good | — |
| Operations | Strong (§5.1.1 ordering) | — |
| Norms | Good | §7.3 input length SHOULD → MUST |
| Safeguards | Strong (SM-01) | SM-02 (JS isolation) and SM-03 (input length) missing IDs |

**Sync Notes**: ✅ Comprehensive.

</details>

### Sync Follow-ups

- After adding Sync Notes to `effective-tokens-specification.md`: run `grep -r "effective_tokens" pkg/` to confirm all implementation files are captured in the table.
- After upgrading MCP Scripts §7.3 from SHOULD to MUST: verify `mcp_scripts_generator.go` enforces the limit and add a test in `mcp_scripts_generator_test.go`.
- After adding forecast λ fixture tests: update `forecast-specification.md` §13 to mark the TODO as resolved.
- After fuzzy-schedule E2E test: update `fuzzy-schedule-specification.md` §11 integration coverage note to reference the new test.

### Context

- **Files reviewed** (rotation indices 0–4, first run):
  - `docs/src/content/docs/reference/effective-tokens-specification.md`
  - `docs/src/content/docs/reference/forecast-specification.md`
  - `docs/src/content/docs/reference/frontmatter-hash-specification.md`
  - `docs/src/content/docs/reference/fuzzy-schedule-specification.md`
  - `docs/src/content/docs/reference/mcp-scripts-specification.md`
- **Next rotation index**: 5 (model-alias-specification.md)
- **Run**: [§26366263282](https://github.com/github/gh-aw/actions/runs/26366263282)







> Generated by [📋 Daily SPDD Spec Planner](https://github.com/github/gh-aw/actions/runs/26366263282) · sonnet46 1.7M · [◷](https://github.com/search?q=repo%3Agithub%2Fgh-aw+is%3Aissue+%22gh-aw-workflow-call-id%3A+github%2Fgh-aw%2Fdaily-spdd-spec-planner%22&type=issues)
> - [x] expires  on May 27, 2026, 4:19 PM UTC

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[spdd] Daily spec work plan - 2026-05-24 #34478

Summary

Priority Work Queue

SPDD Checklist

Per-Spec Findings

/spdd-analysis

/spdd-reasons-canvas

/spdd-analysis

/spdd-reasons-canvas

/spdd-analysis

/spdd-reasons-canvas

/spdd-analysis

/spdd-reasons-canvas

/spdd-analysis

/spdd-reasons-canvas

Sync Follow-ups

Context

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Priority	Task	Spec
P0	Add Sync Notes section to `effective-tokens-specification.md` (no impl-file mapping exists)	Effective Tokens
P0	Upgrade MCP Scripts §7.3 input length limit from SHOULD to MUST norm	MCP Scripts
P1	Add fixture tests for invalid/non-finite λ and zero-projection fallback in `forecast_montecarlo_test.go`	Forecast
P1	Add integration test assertions for `compile_schedule_calendar.go` output in fuzzy-schedule changes	Fuzzy Schedule
P1	Strengthen MCP Scripts §7.2 JS-tool isolation: change SHOULD to MUST for sandbox requirements	MCP Scripts
P2	Add assertion in `forecast.go` / `forecast_command.go` ensuring verbose diagnostics and JSON output share same λ value	Forecast
P2	Clarify §9 Extensibility in Effective Tokens: add normative MUST NOT extension rules and reference `pkg/cli/forecast_montecarlo.go`	Effective Tokens
P2	Track v2.0.0 frontmatter hash migration prereqs — verify all 4 checklist items in issue `#31983` are assigned	Frontmatter Hash

Area	Strength	Gap
Requirements	Strong (RFC-2119, §8)	§9 lacks normative extension constraints
Entities	Good (§3 terminology, §6 node schema)	—
Approach	Good (formula, aggregation)	—
Structure	Good (ToC, sections)	—
Operations	Adequate	No operations ordering for overflow detection
Norms	Good (R-SAFE-001–003A)	SHOULD vs MUST inconsistency in §8.4 partial visibility
Safeguards	Present	No compliance test vectors for overflow/ceiling

Area	Strength	Gap
Requirements	Detailed (R-MC-* IDs)	λ=0 and non-finite λ paths underdefined
Entities	Good (§3)	—
Approach	Strong (Poisson+Bootstrap+Bernoulli)	—
Structure	Good	—
Operations	Good (§6 sampling procedure)	—
Norms	Good	JSON/verbose output λ coupling not normative
Safeguards	Present (§10.6, Appendix F)	No test vectors for non-finite λ

Area	Strength	Gap
Requirements	Strong	—
Entities	Good	—
Approach	Strong (text-based)	v2.0.0 field-selection model not yet designed
Structure	Good	—
Operations	Strong (sync procedure §Sync Notes)	—
Norms	Good (S-1–S-6)	—
Safeguards	Strong	Diamond-import BFS test vector missing

Area	Strength	Gap
Requirements	Strong (grammar, R-SCHED-*)	—
Entities	Good	—
Approach	Strong (FNV-1a, scattering)	—
Structure	Good	—
Operations	Good	Calendar E2E path not tested
Norms	Good	§6.4.2 empty avoidance set behavior unspecified
Safeguards	Adequate	—

Area	Strength	Gap
Requirements	Strong	§7.2 SHOULD → MUST for JS sandbox
Entities	Good	—
Approach	Strong	Go tool container unavailability not covered
Structure	Good	—
Operations	Strong (§5.1.1 ordering)	—
Norms	Good	§7.3 input length SHOULD → MUST
Safeguards	Strong (SM-01)	SM-02 (JS isolation) and SM-03 (input length) missing IDs

[spdd] Daily spec work plan - 2026-05-24 #34478

Description

Summary

Priority Work Queue

SPDD Checklist

Per-Spec Findings

/spdd-analysis

/spdd-reasons-canvas

/spdd-analysis

/spdd-reasons-canvas

/spdd-analysis

/spdd-reasons-canvas

/spdd-analysis

/spdd-reasons-canvas

/spdd-analysis

/spdd-reasons-canvas

Sync Follow-ups

Context

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions