Stop resolving pr: at artifact-write time; set it only in PR-aware skills

[williamthorsen]

Problem

resolve-frontmatter.sh resolves the pr: frontmatter field on nearly every artifact write, shared across about 24 caller skills. This is the wrong layer and the wrong time:

1. The PR usually does not exist yet. Most artifacts (plans, design docs, early change summaries) are written before a branch is pushed, so eager resolution returns nothing precisely when those early artifacts are created. The field is reliably populated only on artifacts written after a PR already exists.
2. A shell script cannot reach the transport that works in MCP-only environments. Where Bitbucket is reachable only through the Bitbucket MCP server, the script cannot perform the lookup, so it punts the work back to the agent and forces every caller to carry a handshake for that case.
3. Nothing reads pr: programmatically. The field is a human-facing backlink in artifact frontmatter. The skills that genuinely need a PR URL obtain it directly at the moment they run (born from creation, passed as an argument, or fetched from the API), never from the frontmatter field.

The result is elaborate, transport-dependent resolution plus a contract duplicated across roughly 24 callers, all to populate a field that has no code reader and is most reliably set only once the PR already exists.

Context

• The pr: field is valued as a human backlink: opening an artifact and jumping to its PR.
• It does not need to be resolved eagerly. It only needs to be stored once the URL is known.
• Storing it on the artifacts that directly relate to PR creation and review is sufficient.

Proposed solution

Remove PR resolution from resolve-frontmatter.sh. The script resolves only the cheap, always-knowable local facts (branch, commit, baseSha, ticket id, ticket ref, platform, timestamp, run id). The pre-check, transport chain, status outcomes, error kinds, and any PR note all go away; the script touches neither the network nor MCP, gh, or curl. pr: remains a canonical field, populated only when a caller passes --override pr=<url>.

Populate pr: only where a URL is genuinely available:

• review-branch (via review-pr) sets pr: from the PR metadata it already holds; in ticket-only / no-PR mode it omits the field.
• respond-to-review forwards pr: from the review artifact it answers; omits it when the review has none.
• create-pr backfills pr: into the change summary it based the PR on, after the PR is created and its URL is known.

summarize-change and every other artifact-writing skill omit pr: — they hold no URL at write time. The PR-creation and merge artifacts continue to record the URL as a prose line (unchanged); they do not use frontmatter.

Delete the failure/deferral handshake from all caller skills and subagents. Shrink pr-resolution.md to the new contract, and update artifact-conventions.md's pr: entry to match.

Acceptance criteria

• resolve-frontmatter.sh attempts no PR lookup, resolves no pr: value, and emits no PR-related note on any path. pr: appears in its output only when supplied via --override pr=<url>.
• No caller skill or subagent carries a PR-lookup failure or deferral trigger line. An rg audit over packages/agents/content finds no remaining references to the canonical failure note.
• Review artifacts carry pr: when produced via review-pr (review-branch sets it; respond-to-review forwards it) and omit it in ticket-only / no-PR mode.
• create-pr backfills pr: into the change summary after the PR is created, so the change summary carries the PR URL once a PR exists.
• pr-resolution.md describes the new contract, with no remaining references to PR lookup, transport, deferral, MCP routing, or error kinds; artifact-conventions.md's pr: entry reflects that the field is set only by PR-aware skills (held URL or backfill) and omitted elsewhere.
• The script's PR-resolution tests are removed; remaining tests cover the local-fact output and that --override pr= populates the field. create-pr's backfill behavior is covered where it has test surface.
• Documentation and help text are updated: the script header, pr-resolution.md, and artifact-conventions.md.

[williamthorsen]

Third issue: wrong assumption about how SCM access is provided

The PR-lookup path assumes the only way to reach Bitbucket is via locally-configured Bitbucket REST credentials, and reports "no Bitbucket credentials configured" when those aren't present. That assumption is wrong in environments where SCM access is mediated differently:

• Bitbucket access via the Bitbucket MCP server. In Rovo Dev sessions (and any other MCP-enabled host), Bitbucket reads/writes go through the bitbucket MCP toolset (bitbucketPullRequest, bitbucketRepoContent, etc.) rather than direct REST + token. The local machine has no Bitbucket API credentials and doesn't need any.
• GitHub access via gh. GitHub repos are reached via the already-authenticated gh CLI, not a raw token in the environment.

So in practice the script reports a "missing credentials" failure on a machine that is fully capable of looking up PRs — just through a different transport. Worse, the rationale ("no Bitbucket credentials configured") is misleading: it implies the user should set credentials, when in fact the script just hasn't tried the transport that is available.

Considerations

• A skill cannot call MCP tools itself (only the agent can), so resolve-frontmatter.sh realistically has three possible transports to consider, in order of preference:
  1. gh pr view --json url (for GitHub remotes).
  2. Bitbucket REST + token (for Bitbucket remotes when token is configured).
  3. Defer to the agent: emit a structured "needs-agent-lookup" status with the remote/branch/commit info, and let the calling skill ask the agent to perform the lookup via MCP and write the result back.
• The status taxonomy from the original issue (skipped / found / not-found / error) needs a new value such as deferred to cover the case where the script knows a PR could exist but the transport it has access to isn't usable for this remote.
• The user-visible note for the deferred case should be informational, not a failure — e.g., Note: PR lookup deferred to agent (Bitbucket remote, no local credentials).

Adjusted acceptance criterion

• Running the script in an environment where the only available Bitbucket transport is the MCP server produces a deferred status (not error) and emits an informational note that doesn't claim credentials are missing.