docs(v0.4.0): freeze processing contracts for history, schedules, alerts, and candidates

[CrisSTEM]

Summary

Freeze the committed v0.4.0 backend-processing contracts before scheduler and derived-signal implementation expands the repository surface.

Linked issue(s)

• Closes docs(data-model): freeze v0.4.0 contracts for history preservation, schedule runs, alerts, and candidates #44

Milestone fit

This PR documents the committed backend-only v0.4.0 scope:

• repeated-run history preservation
• canonical schedule_runs, alert_events, and candidate_suggestions contracts
• timestamp semantics for scheduling and derived signals
• config-to-persistence mapping for alert and candidate processing

It intentionally keeps scheduler execution, alert evaluation, candidate discovery, API work, and frontend work out of scope.

What changed

• documented repeated-run history semantics for fetch_runs, metric_snapshots, and content_items
• froze canonical persistence contracts for schedule_runs, alert_events, and candidate_suggestions
• documented timestamp semantics for scheduler execution, alert generation, and candidate evidence
• clarified how the existing alert-rule and schedule config maps into planned v0.4.0 persisted processing records
• aligned SPEC.md and docs/roadmap.md with the committed backend-only v0.4.0 milestone scope
• documented the planned reviewer-visible SQLite inspection path for the v0.4.0 backend milestone

Out of scope

• scheduler implementation
• alert evaluator implementation
• candidate discovery implementation
• API or frontend read models
• broad repository-wide documentation reconciliation beyond this contract freeze

Validation

Mark what you actually ran:

• python3 ./scripts/trim-whitespace.py --check
• go vet ./...
• go test ./...
• make ci
• Manual CLI verification was performed if runtime behavior changed

Documentation impact

• No docs update needed
• SPEC.md
• docs/
• repository governance docs (AGENTS.md, CONTRIBUTING.md)
• CHANGELOG.md
• release notes

Reviewer focus

• docs/data-model.md for repeated-run history semantics and canonical naming
• docs/configuration.md for config-to-persistence mapping and threshold/window honesty
• SPEC.md and docs/roadmap.md for backend-only v0.4.0 scope alignment
• confirmation that unimplemented scheduler/alerts/candidates work is not implied as already delivered

Auditability checklist

• Branch name follows project convention
• PR scope matches the linked issue and milestone
• Commits were pushed progressively, not as one final dump
• Relevant tests were added or updated for behavior changes
• No secrets or sensitive credentials were introduced
• Deferred follow-up work is documented explicitly
• Unimplemented work is not implied as completed

Notes for merge

Preferred merge method:

• Issue PRs: Rebase and merge
• Release aggregation PRs: Merge commit
• Use Squash and merge only when the branch became noisy and preserving intermediate commits no longer adds value