Make attestation staleness first-class for downstream agents

[caioribeiroclw-pixel]

Roam already has the strongest shape I have seen for local codebase evidence: roam_attest, roam_cga_emit, PR-risk envelopes, dogfood PR comments, and explicit index freshness hints.

One small thing that would make those packets safer for downstream agents/reviewers: make staleness / replay conditions first-class in the attestation output.

Concrete shape I mean:

{
  "schema": "roam.pr_attestation.v1",
  "subject": {
    "kind": "pull_request|commit_range|working_tree",
    "repo": "owner/name",
    "base": "...",
    "head": "..."
  },
  "evidence_scope": {
    "commands": ["roam health", "roam pr-risk", "roam affected-tests"],
    "index_commit": "...",
    "indexed_commit": "...",
    "head_commit": "...",
    "roam_version": "...",
    "rule_config_hash": "..."
  },
  "verdict": "safe|review_recommended|blocked|not_checked",
  "not_checked": ["coverage_unavailable", "runtime_tests_not_run"],
  "verification_command": "roam attest --verify <bundle>",
  "stale_if": [
    "head_commit_changed",
    "indexed_commit != head_commit",
    "rule_config_hash_changed",
    "roam_version_major_changed",
    "coverage_import_changed",
    "target_branch_moved"
  ],
  "privacy": {
    "raw_source_included": false,
    "raw_prompt_included": false,
    "secrets_included": false
  }
}

The key bit is not the exact names. It is that an agent reading a Roam attestation later can answer: can I still use this as authority, or do I need to rerun the evidence?

Why this seems useful:

• Roam's current envelopes already expose freshness hints like indexed_commit != HEAD; promoting that into a stable stale_if/not_checked contract would make the packet easier to consume from Claude Code, Codex, CI, or another reviewer without parsing prose.
• It keeps the proof local/privacy-safe. No raw prompts, transcripts, source bodies, or secrets need to be embedded.
• It turns roam_attest from “a good review artifact now” into a replay-safe handoff artifact: useful when a PR is resumed by another agent, rebased, re-reviewed after dependency changes, or summarized in a merge note.

If this already exists under a different command/flag, the discoverability gap may just be docs: a short “when is a Roam attestation stale?” section would solve most of it.

[Cranot]

Thank you — this is one of the best-shaped feature requests we've had. You gave us the exact field names (stale_if / not_checked / verification_command / privacy), the reason they matter (replay-safe handoff between agents), and you correctly guessed it was partly a discoverability gap. That precision made it easy to say yes, so we just shipped it.

What was already true (you were right)

roam was already computing every raw signal — it was just scattered across three subsystems and none of it landed in the durable roam attest body:

• resolve.index_status() already emits {indexed_commit, head_commit, dirty_files} — the indexed_commit != HEAD hint you saw. But it was only stamped into _meta when the index was already stale, so a reader of a fresh-at-emit attestation got nothing.
• the index manifest already records config_hash + roam_version + schema_version + enabled-extras drift (surfaced today via roam doctor).
• roam cga verify already re-derives the graph digests and refuses on a commit/dirty/graph mismatch.

The signals were real; they just weren't promoted into one stable, named contract.

The actual gap — and the fix

Your stale_if framing inverts the current model in exactly the right way. Today roam evaluates freshness at emit time, for the current process. Your contract instead records the baseline inside the attestation (indexed commit, head, config hash, roam version, base-branch SHA) so a downstream agent reading it later can evaluate the conditions itself. That inversion is the feature, and we adopted it.

roam attest now emits, on the attestation body:

{
  "indexed_commit": "…",          // promoted out of _meta, unconditionally
  "head_commit": "…",
  "stale_if": [
    {"condition": "head_commit_changed", "baseline": "…", "check": "…"},
    {"condition": "indexed_commit_behind_head", "baseline": {…}, "already_true": false},
    {"condition": "working_tree_dirty", "baseline": {…}, "check": "…"},
    {"condition": "rule_config_hash_changed", "baseline": {…}, "check": "…"},
    {"condition": "roam_version_major_changed", "baseline": "…", "check": "…"},
    {"condition": "coverage_import_changed", "baseline": {…}, "check": "…"},
    {"condition": "target_branch_moved", "baseline": "…", "check": "…"}
  ],
  "not_checked": ["risk_score", "blast_radius"],   // honest, derived from degraded collectors
  "verification_command": "roam attest <base>..<head> --format json",
  "privacy": { … }
}

Notes on the design choices, since you clearly think about downstream consumption:

• stale_if reuses the manifest's drift vocabulary so the condition names stay aligned with roam doctor, and each entry carries its baseline so a later reader can re-evaluate without re-running roam.
• not_checked is derived, not decorative — if the graph extras (networkx) weren't available, risk_score/blast_radius show up here automatically; if no rules ran, budget_rules; if no tests were selected, affected_tests. It reflects what this specific run actually skipped.
• It lives on attestation, not evidence. That keeps the two axes clean: --sign's content_hash covers evidence-tamper, stale_if covers freshness. The signed hash stays byte-stable across this change.

One honesty caveat on privacy

You framed it as privacy-safe, and it nearly is — the attestation carries sha256 hashes + counts, never source bodies/prompts/transcripts/secrets, telemetry: "none", network_required: false, and clone-URL credentials are already stripped. The one thing I don't want to over-claim: it does embed symbol/identifier names (in breaking-changes / effects / tests). So the block states source_code_included: false and identifiers_included: true rather than implying zero content leakage. If redactable identifier names would matter for your use case, say the word — that's a natural follow-up.

If any of the stale_if condition names feel wrong for how you'd consume them downstream, I'd genuinely welcome the input before they harden into something people script against. Thanks again for the unusually clear write-up. 🙏