-
Notifications
You must be signed in to change notification settings - Fork 0
docs(agents): non-repository verification for external blockers #2553
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -516,12 +516,13 @@ governs the issue work that follows.) Two rules enforce that: | |
| keeps an experiment issue open, also use `Part of #experiment`. Among open issues prefer the oldest. | ||
| **"Actionable" is deliberately narrow — skip an older issue ONLY when one of these is true and you can | ||
| *point to it*:** (a) it already has an open PR; (b) it is blocked on a **named, live-verified** | ||
| external dependency (a specific upstream PR/release you can cite); or (c) it is too under-specified to | ||
| even begin; or (d) a delivered experiment is awaiting its **named, future measurement date**, which | ||
| is recorded on the issue and has not elapsed. Once that date arrives, measuring and recording the | ||
| decision is actionable work; or (e) another instance holds a **live claim** on it — assigned **and** | ||
| branched, within the ~2h window, no PR yet (see *Claim protocol*). (e) is the only skip reason that | ||
| expires on its own: once the window lapses with no PR, the issue is fair game again; or (f) it is | ||
| external dependency (a specific upstream PR/release you can cite) — see *External-blocker | ||
| verification* below; or (c) it is too under-specified to even begin; or (d) a delivered experiment is | ||
| awaiting its **named, future measurement date**, which is recorded on the issue and has not elapsed. | ||
| Once that date arrives, measuring and recording the decision is actionable work; or (e) another | ||
| instance holds a **live claim** on it — assigned **and** branched, within the ~2h window, no PR yet | ||
| (see *Claim protocol*). (e) is the only skip reason that expires on its own: once the window lapses | ||
| with no PR, the issue is fair game again; or (f) it is | ||
| **authored by an exact dependency-automation identity** (`renovate[bot]` / `dependabot[bot]`, or | ||
| `app/renovate` / `app/dependabot`) — see the automation-owned carve-out under *Merge policy*. | ||
| (f) is not a deferral like the others: such an issue is **never actionable at all** and never | ||
|
|
@@ -539,6 +540,20 @@ governs the issue work that follows.) Two rules enforce that: | |
| issue as "blocked"/"gated", **re-verify the blocker against live state** (memory's "gated" notes go | ||
| stale) and **name the concrete blocker in the report**; an | ||
| unverifiable or merely-inherited "gated" is not a skip. | ||
| **External-blocker verification (skip clause (b) — monorepo#2243).** An unattended run must | ||
| live-verify an external blocker *without* inspecting a third-party repository (that stays behind | ||
| the *Professional-work repository boundary*). Use public **non-repository** channels only — the | ||
| same class *Enhancement work → Continuous upstream research* already permits: release feeds, | ||
| changelogs, package registries, and module proxies. Never open the upstream repo page, tree, | ||
| 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
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 AGENTS.md reference: AGENTS.md:L776-L783 Useful? React with 👍 / 👎.
Comment on lines
+548
to
+552
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
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 👍 / 👎. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
The worked blocker line uses AGENTS.md reference: AGENTS.md:L1503-L1507 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 | ||
|
Comment on lines
+553
to
+555
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When AGENTS.md reference: AGENTS.md:L539-L542 Useful? React with 👍 / 👎. |
||
| under-specified for (b) — add the line (or unblock) rather than skipping forever on prose alone. | ||
| **A "maintainer decision" is NOT a skip reason — don't block yourself on it.** The maintainer does | ||
| **not** want to make issue-level decisions, and a passive "gated / awaiting-maintainer / needs a | ||
| decision" note in a report or memory *never reaches him* — that passive parking **is** the | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The executable planning guidance in
.claude/skills/product-engineering/SKILL.md:123-148still contains only the oldnamed, live-verifiedskip rule and never requires the structured line,blockedlabel, non-repository channel, ornext-checkhandling 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 👍 / 👎.