Topic · role references resolve

Role references resolve

Gist

Role references resolve is a dangling checks:, topics:, documents:, or classes: entry on a builtin or project role. Proof runs proof audit --check role_references_resolve. Empty-is-win language is not that hop. Jama still authors.

proof audit --check role_references_resolve

Keep the role if the procedure is still the one you want. Keep Jama if it already holds the shalls. Neither one fails the merge when a role still names a check that was renamed last week.

Request demo Last silent drop vs this hop

01 · The silent drop

A role that names a dead check will send the next agent there.

You can keep the playbook on disk. If checks: still lists a renamed id, the worker follows a door that is gone. The audit then records a quiet result as if the map was current.

The check is role_references_resolve. It is verify-stage. Severity of a dangling reference is warning, not fail. It reads every installed role from proof role list: builtin bodies, and project proof/roles/<name>.md. Default-on. Explicit project.checks.role_references_resolve.enabled: false reports skip, never pass.

Each role declares machine-checkable references in frontmatter. The hop resolves them against the live registries:

checks: must be a registered audit check. topics: must resolve to a real proof help topic. documents: on a project role must be a requirement id in this project's spec. classes: must be a class in the effective catalog. A backticked token in the body that is a registered check id, and is missing from checks:, is a prose-check finding. A mission over 200 characters is a mission-length warning.

A hit names the role, the kind, the bad value, and how to fix it. A renamed check, a deleted help topic, a retired requirement, or a catalog class that is not in the effective catalog makes the role quietly mislead the next agent that reads it.

# proof/roles/hazard-sweep.md
checks:
  - hazard_sweep_that_was_renamed
# proof audit --check role_references_resolve
# [VERIFY] role_references_resolve -- 1 dangling role reference(s) across 1 role(s)
# role "hazard-sweep": check reference "hazard_sweep_that_was_renamed" does not resolve
# silent drop: the playbook shipped. the door is gone

A project with no project-local roles still checks the builtin set. Builtin documents: name Proof's own requirement ids, which a downstream project does not carry, so that one kind is not resolved in the live audit. Builtin checks, topics, classes, prose-routed checks, and mission length are resolved here. Builtin documents: stay a build-time gate on the CLI.

Edit the named role. Point the reference at a real check, topic, requirement, or class, or remove the stale entry. Then re-run the same check. Do not mint a Jama note to carry the skip.

proof audit --check role_references_resolve
proof role list
proof role show hazard-sweep
proof audit --list-checks
proof help --list
proof catalog list

02 · The exhibit

Same role. A silent drop, or this hop.

One role file. checks: still lists an id that was renamed. Click the tabs.

The role

Ask did the playbook file still exist
Stamp checks: hazard_sweep_that_was_renamed
Why a named door that is gone is an instruction to walk into a wall

Playbook green

This hop

Nobody asked whether the role still names a registered check. A green playbook is not a current map. The finding kind is this hop.

Frontmatter unread

The role

Keep the role file. Keep the Jama shall. That is not this hop.

Keep the record

Proof

Ask does checks, topics, documents, or classes still name something that does not resolve
Out role "hazard-sweep": check reference "hazard_sweep_that_was_renamed" does not resolve

Silent drop counted

Same role. A silent drop, or this hop. Click the tabs.

Surface	What they do	What Proof does	What we lose
Role prompt hygiene	Empty-is-win or max-N-findings language in the body.	Whether the frontmatter still names a live check, topic, requirement, or class.	Not the prompt hop. See role prompt hygiene.
Autolink clean	A comment prefix that never joins the graph.	A role map that still names a door that is gone.	Not the autolink hop. See autolink clean.
Documentation coverage	Whether a requirement has a docs witness at all.	Whether the role that claims to be that witness still points at a real id.	Not the coverage hop. See documentation coverage.
Help topic list	`proof help --list` names topics that exist today.	A role `topics:` entry that no longer resolves.	We do not author the help page. A stale topic id is this hop.
Jama cell	A shall, and a note if you type it.	A warning the audit can name next to the role.	Not Jama's V&V. Jama still authors. We have not run a frozen Jama pack.

The teaching graph is still one role whose board called the playbook done and whose checks: still listed a renamed id. Close it by editing the named role. Do not treat a Jama note as this hop. Do not treat a green playbook stamp as a current map.

# proof/roles/hazard-sweep.md
checks:
  - role_prompt_hygiene
topics:
  - role
  - audit
classes:
  - hazard.unhandled
# proof audit --check role_references_resolve
# all role references resolve (N built-in + 1 project-local role(s) checked)

The prompt hop stays on role prompt hygiene. The autolink hop stays on autolink clean. Jama still authors. Proof vs Jama.

03 · The honest loss

Proof names the dangling id. It does not rewrite the role, and it does not prove the Go.

A quiet proof audit --check role_references_resolve can still mean the builtin set resolved, or a skip because the check is off. Jama still authors.

Warning, not fail. Promote once the corpus is clean. Switched off is skip, never pass. A project with no project-local roles still reports that the builtin reference set resolves. Builtin documents: are not resolved in the live audit. A disabled catalog class is unresolved. Overlay-only classes in the effective catalog do resolve. Prose-check findings only fire on backticked tokens that are registered check ids today. A glob such as spec_lint_* is not a finding. The hop does not rewrite the role. It does not inspect the agent runtime. It does not score whether the worker followed the procedure. It does not prove the Go. Copied live ids still pass. We have not scored this floor against a frozen Jama pack or a ReqIF export. The loss is named, not scored.

The prompt hop stays on role prompt hygiene. The engagement stays on software correctness audit. Jama still authors.

Request demo How the install is bought

04 · Nearby questions

What people type next.

What is role references resolve? Same question. Same URL.

Is this role prompt hygiene? No. That hop is empty-is-win or finding-quota language in the body. This hop is a frontmatter id that no longer resolves. See role prompt hygiene.

Does a project with no local roles pass trivially? No. Builtin roles always ship. The hop reports that the builtin reference set resolves.

Are builtin documents: checked here? No. Those ids name Proof's own requirements. A downstream project does not carry them. They are a build-time gate on the CLI. Builtin checks, topics, and classes are still this hop.

Is a disabled catalog class a hit? Yes. The class must exist in the effective catalog. Overlay-only classes that are loaded do resolve.

Is a backticked check in the body a hit? Yes, if it is a registered check id and it is missing from frontmatter checks:. The fix is to list it. Do not delete the prose.

Does a green hop prove the agent followed the role? No. The hop observes the map. It does not inspect the worker.

Is Proof a Jama alternative for the shall? No. Jama still authors. Proof vs Jama.