Board: freeze the provider-neutral observation contract and truth fixtures

[jeffhuber]

Part of #945 and roadmap #900.

Problem

Board has no single closed local observation model that can represent session, work, run, role, provider, repository/worktree, lifecycle, freshness, and next-actor evidence without importing private provider state or inventing activity.

Scope

Define a versioned provider-neutral Board observation/read-model contract and offline adversarial fixtures. Reuse the lifecycle state/reason/action vocabulary and safe public_projection semantics from #906. Define validated opaque correlation keys, exact repository and resolved-worktree binding, event time versus observation time, per-source freshness/coverage, observed versus provider-reported state, safe work stages, waiting/attention reasons, next-actor precedence, PR/head association, heartbeat evidence, and explicit unavailable/null measurement semantics.

This issue defines the local Board contract and fixtures only. It does not change presentation, add producers, create a second lifecycle state machine, widen public_projection, add cloud events/fields, or map Slack-specific data.

Coordination and dependencies

• Reuse Sessions: provider-neutral remote lifecycle and recovery #906 / PR Sessions: add provider-neutral remote lifecycle and recovery #928.
• Align the checkout/session identity vocabulary with Sessions: discover the current local brief and lease from a checkout #935, while leaving discovery implementation in Sessions: discover the current local brief and lease from a checkout #935.
• Leave Slack-specific and hosted/cloud mappings in Slack: freeze telemetry contract and implement OSS Board/cloud emitters #921.

Acceptance criteria

• Schema and fixtures cover assigned, dispatched, observed running, provider-reported progress, waiting for user, waiting for approval, implementation complete, failed, cancelled, reviewed, ready, merged, stale, source unavailable, unlinked, and no-work states.
• One work item can carry multiple ordered reasons but yields one deterministic primary next actor/action from a closed table.
• Freshness and coverage are per source; failed refresh preserves a dated last observation and cannot become a live claim.
• A lease proves coordination ownership only, labels prove requests only, process presence without binding stays unlinked, and a publisher workflow is distinct from the authoritative gate verdict.
• Missing time, cost, quality, productivity, or provenance remains explicit null/unavailable and cannot serialize as zero or success.
• Session objective/title is allowed only through an explicitly authorized bounded display label.
• Contract and fixtures contain no source, diff, task/issue body, prompt, transcript, message, context packet, graph content, credentials, raw provider output, personal path, PID-derived identity, or secret.
• Unknown enum/field, identity mismatch, worktree mismatch, cross-session join, invalid timestamp, and oversized value fail closed.

Initial ownership

Provider-neutral session/events track. Planned builder: Code Mower Codex. This contract must be reviewed before dependent producer or presentation merges.

Code Mower delivery

Produce one independently reviewable PR for this issue. Record the named Code Mower builder, keep one writer on the branch, obtain an independent audit against the exact current head, resolve every P0/P1/P2 finding, and pass focused tests, relevant full tests, privacy checks, normal CI, and code-mower/gate. Upload only allowlisted metadata. No umbrella PR.

Existing PR and refreshed completion gate

Continue existing PR #956; do not create a duplicate implementation PR. It is draft and behind main. Refresh #956 first, then #957, preserving one writer per source area. Re-run the independent exact-head audit, focused/relevant tests, CI, and authoritative gate on every changed head; historical passing evidence is retained only for its original head. Contract/fixture implementation may merge after those checks without waiting for the Graphify tag. Board release #952 remains ordered after #915's release or explicit deferral.

#935 is complete through #973 and its resolver must be reused. Role/contributor/evidence integrations remain #975/#963/#976 and their consuming children; no new provider state machine or cloud fields are added here.

[jeffhuber]

B0 implementation and hold record

Named builder: Code Mower Codex (codex_desktop)

• Draft PR: Board: freeze provider-neutral observation contract #956
• Exact head: 0feb5f98374622956bbc71158c6a1147a0df253c
• Independent Code Mower Claude exact-head audit: PASS, P0=0, P1=0, P2=0, P3=0 (evidence)
• Focused contract validation: 15 tests passed under unittest and pytest
• Relevant validation: 348 tests and 572 subtests passed
• Full supported suite: 3,004 tests passed, 11 skipped
• Ruff, compile, privacy scan, diff check, wheel/sdist build, Python 3.12/3.13/3.14 CI, and code-mower/gate: passed
• Privacy/scope: local contract and offline fixtures only; no UI, cloud fields/events, Slack mapping, provider mutation, lease mutation, or private payload upload

PR #956 intentionally remains draft and unmerged behind active Devin PR #940 and the v1.4.0/v1.4.1 release ordering.