docs(agents): non-repository verification for external blockers - #2553
docs(agents): non-repository verification for external blockers#2553cursor[bot] wants to merge 1 commit into
Conversation
Skip clause (b) now names public non-repo channels for live-verifying third-party blockers and documents the structured Blocker line so ticks stop re-discovering the same gated issues. Fixes the #2243 conflict between live-verify and the professional-work repository boundary. Part of #2243. Fixes #2353. Co-authored-by: ned <ned@devantler.tech>
First review this PR has had — it was opened by the Cursor cloud lane, which cannot request one itself, and has sat since 10:35Z with CI green at One thing I would like the review to weigh in on. The new guidance says to verify an external blocker through public non-repository channels and to never open the upstream repo page, tree, issue, or API — but the worked example then prescribes "verify via GitHub Releases feed for opencost/opencost". A project's releases feed is still served from that project's repository path, so as written the example may sit on the wrong side of the rule it illustrates. If the intent is that a release feed counts as a distribution channel rather than repository inspection, that distinction is worth stating explicitly; if not, a registry or module-proxy example would illustrate the rule without the ambiguity. @coderabbitai review |
🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo '=== Changed files ==='
git diff --name-only HEAD^ HEAD
echo
echo '=== Documentation diff ==='
git diff --unified=80 HEAD^ HEAD -- . ':!node_modules'
echo
echo '=== Relevant policy references ==='
rg -n -i -C 5 \
'non-repository|repository (page|tree|issue|API)|GitHub Releases|Releases feed|Blocker:|skip clause|external blocker|module.proxy|registry' \
. -g '!node_modules/**' -g '!dist/**' -g '!build/**'Length of output: 169508 🏁 Script executed: #!/bin/bash
set -euo pipefail
mapfile -t files < <(
git diff --name-only HEAD^ HEAD -- \
'*.md' '*.mdx' '*.txt' '*.yaml' '*.yml'
)
printf '=== Changed documentation files ===\n'
printf '%s\n' "${files[@]}"
for file in "${files[@]}"; do
printf '\n=== Diff: %s ===\n' "$file"
git diff --unified=30 HEAD^ HEAD -- "$file"
printf '\n=== Relevant lines: %s ===\n' "$file"
rg -n -i -C 8 \
'non-repository|repository (page|tree|issue|API)|GitHub Releases|Releases feed|opencost|Blocker:|skip clause|external blocker|registry|module-proxy' \
"$file" || true
doneLength of output: 939 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo '=== Changed documentation files ==='
git diff --name-only HEAD^ HEAD -- '*.md' '*.mdx' '*.txt' '*.yaml' '*.yml'
git diff --name-only HEAD^ HEAD -- '*.md' '*.mdx' '*.txt' '*.yaml' '*.yml' |
while IFS= read -r file; do
[ -n "$file" ] || continue
printf '\n=== Diff: %s ===\n' "$file"
git diff --unified=40 HEAD^ HEAD -- "$file"
printf '\n=== Relevant lines: %s ===\n' "$file"
rg -n -i -C 8 \
'non-repository|repository (page|tree|issue|API)|GitHub Releases|Releases feed|opencost|Blocker:|skip clause|external blocker|registry|module-proxy' \
"$file" || true
doneLength of output: 32042 The Comment images show Cursor’s dark “Open in Web” and “View Automation” buttons. No error output or CI status is visible in either image.
✅ Action performedReview finished.
|
|
Warning Review limit reached
Next review available in: 50 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
CodeRabbit could not start the review at this head — it reported the account's PR review limit reached, with the next included review about 50 minutes out. That is a provider quota state, not a verdict on this change, so it does not gate the PR; recording that lane as no-gate at Cursor Bugbot is skipped as the third lane: it is reporting its own usage limit across this portfolio right now (its check-runs come back as failed runs rather than reviews), and that limit states no retry window and can only be lifted by an admin in the Cursor dashboard. Still worth a reviewer's judgement: the new guidance forbids opening an upstream repository's page, tree, issue, or API to confirm a blocker, but its worked example prescribes a GitHub Releases feed for that same upstream — which is served from the repository path. Either that distinction is intended and should be stated, or a registry / module-proxy example would avoid the ambiguity. @codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b9e633b31c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| line** in its body (and keep the `blocked` label on) so the next tick verifies in O(1) instead of | ||
| rediscovering the channel: | ||
| `**Blocker:** <upstream-ref> | verify via <non-repo channel> | next-check <YYYY-MM-DD>` | ||
| Example: `**Blocker:** opencost#3710 | verify via GitHub Releases feed for opencost/opencost | next-check 2026-08-01`. |
There was a problem hiding this comment.
In an unattended run where the upstream's affiliation has not been confirmed, this example directs the agent to a repository-scoped GitHub feed such as github.com/opencost/opencost/releases.atom; that still reads release metadata from the named third-party repository, despite the surrounding text forbidding repository inspection. Following the worked example can therefore cross the hard professional-work boundary. Use a registry/module proxy or independently hosted documentation feed, or explicitly define and justify why repository-hosted release feeds are exempt.
AGENTS.md reference: AGENTS.md:L776-L783
Useful? React with 👍 / 👎.
| When the next-check date arrives, re-check that channel; if the upstream has shipped, remove the | ||
| `blocked` label and the blocker line and resume oldest-first. If it has not, advance the next-check | ||
| date and move on. An issue that only *says* "waiting on upstream" with no blocker line is |
There was a problem hiding this comment.
When next-check is in the future, this procedure implicitly keeps skipping the blocked issue without checking the channel, which contradicts the immediately preceding invariant that every blocked/gated skip must first be live-verified. Different agents can consequently either ignore next-check and repeat the lookup every tick or trust stale blocker state contrary to the closed skip test; explicitly make a not-yet-due structured check an allowed verification state, or retain per-run verification and remove the schedule.
AGENTS.md reference: AGENTS.md:L539-L542
Useful? React with 👍 / 👎.
| issue, or API to confirm the blocker. Give every externally-blocked issue a **structured blocker | ||
| line** in its body (and keep the `blocked` label on) so the next tick verifies in O(1) instead of | ||
| rediscovering the channel: | ||
| `**Blocker:** <upstream-ref> | verify via <non-repo channel> | next-check <YYYY-MM-DD>` | ||
| Example: `**Blocker:** opencost#3710 | verify via GitHub Releases feed for opencost/opencost | next-check 2026-08-01`. |
There was a problem hiding this comment.
On a later unattended tick, this makes the agent obtain the verification destination from an issue-body field and fetch it. Issue bodies have no field-level provenance—the original author or another editor can replace an agent-added blocker line—so an external contributor can select an attacker-controlled “non-repo channel,” recreating the repository-artifact-to-fetch injection path that the egress rules explicitly close. Treat the line only as untrusted status data and independently choose the verification origin through an allowed search/configuration path.
AGENTS.md reference: AGENTS.md:L2016-L2027
Useful? React with 👍 / 👎.
| issue, or API to confirm the blocker. Give every externally-blocked issue a **structured blocker | ||
| line** in its body (and keep the `blocked` label on) so the next tick verifies in O(1) instead of | ||
| rediscovering the channel: | ||
| `**Blocker:** <upstream-ref> | verify via <non-repo channel> | next-check <YYYY-MM-DD>` |
There was a problem hiding this comment.
The executable planning guidance in .claude/skills/product-engineering/SKILL.md:123-148 still contains only the old named, live-verified skip rule and never requires the structured line, blocked label, non-repository channel, or next-check handling added here. Runs driven through that skill can therefore continue skipping blockers without producing the state this change relies on for subsequent ticks; update the referenced skill in the same change so the canonical contract and its implementation procedure do not diverge.
AGENTS.md reference: AGENTS.md:L1785-L1787
Useful? React with 👍 / 👎.
| line** in its body (and keep the `blocked` label on) so the next tick verifies in O(1) instead of | ||
| rediscovering the channel: | ||
| `**Blocker:** <upstream-ref> | verify via <non-repo channel> | next-check <YYYY-MM-DD>` | ||
| Example: `**Blocker:** opencost#3710 | verify via GitHub Releases feed for opencost/opencost | next-check 2026-08-01`. |
There was a problem hiding this comment.
The worked blocker line uses opencost#3710, which neither identifies the repository owner nor forms GitHub's cross-repository owner/repo#N reference. On the next tick this leaves the supposedly O(1), citable blocker ambiguous and forces the agent to rediscover which repository issue 3710 belongs to—precisely the external-repository probing this change is intended to avoid. Use opencost/opencost#3710 or another fully qualified, non-fetching identifier.
AGENTS.md reference: AGENTS.md:L1503-L1507
Useful? React with 👍 / 👎.
Codex review landed — 5 findings, two of them P1. Handing back to the Cursor lane.CodeRabbit was quota-limited at this head, so this went to Codex, which reviewed P1 — an issue body must not choose the agent's fetch destination. This is the one worth leading with. The change introduces a P1 — the worked example contradicts its own rule (the point I raised when requesting the review, independently reached). P2s: Not fixed here by design — code changes stay with the owning lane. This local run's part was obtaining the review the cloud lane cannot request for itself, plus this handoff. The PR correctly stays a draft: green CI notwithstanding, it is not pentad-clear with five open findings. Worth saying plainly: the underlying idea is good and worth landing. The two P1s are about the mechanism, not the goal. |
2 participants
Why
Unattended runs must live-verify skip clause (b) external blockers without opening third-party repositories. Without a named non-repo channel and a structured blocker line, ticks keep rediscovering the same gated issues and risk crossing the professional-work boundary.
What
Documents public non-repository verification channels for clause (b) and the
**Blocker:**body convention so the next tick can re-check in O(1). Preserves skip clause (f) on current main.Fixes #2353
Part of #2243