Skip to content
113 changes: 97 additions & 16 deletions .claude/guides/merge-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,9 +129,11 @@ self-progressing under the evidence-bound rule below; once that evidence fails o
yours too.

**Three terminal states, and CLOSING is first-class.** A PR is done when it is **merged**, **closed
with the reason recorded**, or **parked on a named, live-verified blocker**. Close one when it adds no
value, duplicates work already shipped, or conflicts with where the product is going — re-filing any
still-valid finding as an issue first, and stating the reason on the PR. A stale draft nobody will
with the reason recorded**, or **parked on a named, live-verified blocker**. A park is that state
only while the parked digest reports the PR `PARKED`, and even then its blocker stays owned (see
*A park is never a resting place* below). Close one when it adds no value, duplicates work already shipped, or conflicts with
where the product is going — re-filing any still-valid finding as an issue first, and stating the
reason on the PR. A stale draft nobody will
finish is not neutral: it costs review capacity, ages into conflicts, and hides the work that matters.

**A parked PR carries one blocker record, in a comment, under the `blocked` label** (monorepo#3424).
Expand Down Expand Up @@ -189,16 +191,17 @@ and its one record is `MALFORMED`, `STALE`, `NO-ASK` or `STALE-ASK` as an issue'
comment by `devantler` whose first line is a `> 🤖 Generated by the …` disclosure counts, so nobody
else's comment can park a PR or clear a finding, and a record written without that line is not seen.

**A parked PR is a terminal state, and the survey reads it as one** (monorepo#3288). After the
**A parked PR is settled for the survey only while the digest says so** (monorepo#3288). After the
survey, run `.claude/scripts/blocked-label-blocker-line.sh --org devantler-tech --parked-digest`. It
prints one row for every open PR that carries the `blocked` label and a closing `CHECKED` line that
counts them:
counts them. Its `actionable=` count includes the `STRANDED` rows:

- `PARKED <repo>#<n> [<note>] <blocker>`: the PR has one conforming record, re-verified recently, and
no blocker it names is known to be closed. It is finished rung-1 work. Do not diagnose it again or
comment on it, and do not count it against `nothing_on_fire`, whatever the survey digest says
about that PR. The note says what was read. `blocker open`: every issue or PR of this
organization that the record names was read and is open. `blocker state not read`: the record
no blocker it names is known to be closed. The PR itself needs no work this run. Do not diagnose it
again or comment on it, and do not count it against `nothing_on_fire`, whatever the survey digest
says about that PR. Its blocker is still owned work (*A park is never a resting place* below).
The note says what was read. `blocker open`: every issue or PR of this organization that the
record names was read and is open. `blocker state not read`: the record
names none the digest may read (another owner's, or a blocker described only in words), so
checking that blocker when the record's date comes due is still yours. `authority`: the PR waits
on a decision, and the digest never reads an authority blocker's state; it separately verifies
Expand All @@ -211,12 +214,87 @@ counts them:
blocks it now. `BLOCKER-SELF` and `BLOCKER-UNREADABLE` mean the record names the PR itself or a
reference with no usable number: write a real blocker or unpark. Any other reason is the record's
own verdict from the paragraph above: repair the record, or unpark the PR.

Exit `0` means every labelled PR is parked, `1` that at least one is actionable, and `2` is UNKNOWN:
then nothing is read as parked, and every labelled PR stays in the survey's own disposition.
- `STRANDED <repo>#<n> reason=<reason> age=<n>d <blocker>`: an exact `dependabot[bot]` or
`renovate[bot]` PR whose park would otherwise hold, but which is still owned rung-1 work this run.
`age` counts days since its record comment was created, which is the PR's first park: `unpark`
keeps that comment and a later `park` reuses it, so a re-park keeps its age. A record comment
removed by hand would reset the age, so park and unpark only through the helper. A labelled PR
whose author is not named is UNKNOWN. `reason=UNCLAIMED`: an open issue of this organization that
an upstream-kind record names is not parked itself, and no open, unparked PR by anyone but a
dependency bot references it (as `owner/repo#N` from anywhere, or as `#N` after a word such as
Fixes or Part of from a PR in the issue's own repository), so no PR is working on it. A PR parked
on that issue does not hold it, and neither do PRs on its sub-issues. The
digest does not read `agent-claim/<issue>` tips: check the claim protocol's signals, then claim it
and work it to a terminal state, or park it on what really blocks it. An assignee does not count
as holding it. `reason=NO-ROUTE`: parked more than 14 days
(`--stranded-max-age-days`), whatever the blocker kind, and the record's result does not carry a
current route record. `reason=ROUTE-LAPSED`: its re-check date has passed. Either way, take the
next engineering route yourself and record it. The digest only reads a route record written
into the record's result, after `last-verified`, as `;`-separated segments: exactly one that
starts `tried: <the route and what it showed>`, one that starts
`next: <the engineering route you take next>`, and one that is exactly `re-check <YYYY-MM-DD>`,
from today up to 14 days ahead. That segment is the only place the result may use re-check as a
word: a date inside a `tried:` or `next:` value, or anywhere else, makes it no route, while
"re-checked" in prose does not count. The digest cannot judge what `next:` says. Writing a wait
or an ask there still counts as no route.
For example:
`…: open; tried: pinning vcluster v0.30, still needs k8s 0.36; next: patch the vendored client; re-check 2026-11-20`.
An authority park needs the route record too: a maintainer ask never pauses the work.
A park date, author or blocker label that cannot be read is UNKNOWN.

Exit `0` means every labelled PR is parked, `1` that at least one is actionable or stranded, and
`2` is UNKNOWN: then nothing is read as parked, and every labelled PR stays in the survey's own
disposition.
Only this digest makes a PR parked. The label alone, a comment that says so, or an earlier run's
note never does, so nobody else's comment can take a PR out of the sweep.

**A park is never a resting place** (agent-plugins#699; the `portfolio-maintenance` PR-driving
procedure holds the portable rule). `PARKED` means only that the PR needs no work on itself this run.
What blocks it is still owned, and a parked PR is never merged while it is parked: run `unpark` once
its blocker verifiably clears, then drive it under the normal gates. When you park a PR, disable
its auto-merge request and dequeue it from any merge queue, so the park holds the merge. On
2026-11-12 every open
Dependabot PR in the portfolio was parked: nine ksail gomod PRs waited on one issue, the oldest since
2026-10-05, and they filled that ecosystem's open-PR limit of 10, so no new Go update could open.

- **An in-portfolio blocker is rung-1 finishing work**, ahead of any Ready pull. Claim it under the
claim protocol and drive it, or park it on its own blocker so the issue sweep checks its record.
- **An upstream blocker is re-checked against live releases on every record re-verification**, at
most 7 days apart. Each check also weighs a route around the wait: adapt to the new version, fork
or patch the dependency, isolate or replace the conflicting dependency, contribute upstream under
the egress rules, or split out or ignore only the blocked part of a grouped update so the rest
merges. To ignore part of an update, use the ecosystem's configuration with the range recorded
beside it, and track it on an issue in this organization that stays open until the ignore is
removed. Do not write about it on the upstream artifact. Remove the ignore when the blocker
clears. Never close the PR to do it: see *Never close a Dependabot PR to retrigger it*.
- **A blocker clears only when its fix is verifiably available to the product**: merged in the
portfolio, or released in a version the PR can take. An upstream item closed without a released
fix, or closed as not planned, still holds: when the digest reports `record=BLOCKER-CLOSED` for
one, re-park on what really blocks the PR now. A scope or design decision clears once the
decision is recorded in the park record and the change it requires is on the PR or merged.
- **Past 14 days, waiting is no longer a route.** Take engineering routes yourself, and keep
taking them until the PR merges or a newer update supersedes it. Closing it otherwise is the
separate decision that the release is unwanted (*Never close a Dependabot PR to retrigger it*),
never a way to free a slot or clear the bound. On each route, edit the park record in place:
its one `tried:` segment names the latest route and what it showed, and its one `next:` segment
names the route after it (the `STRANDED` reasons above). The `next:` route is engineering you will
do, never a wait or an ask.
- **Ownership stays with the agent** (maintainer direction 2026-11-13: *"You own the code, I do
not."*). A park never hands work to the maintainer, and no bound or timer in these rules makes
contacting the maintainer the outcome. A `maintainer-ask` is only for a genuine question of
direction you cannot settle on your own, never about what agents can do themselves. It is never a
handoff and never a substitute for the work: its default is what you will do if no answer comes,
and the routes continue meanwhile.
- **An update ecosystem stalls at its open-PR limit.** When parked PRs bring one configuration
entry's open PRs to its effective `open-pull-requests-limit` (the configured value, or the tool's
default when unset), new version updates stop opening. Dependabot's security updates have a
separate limit. One short of the limit is the last free slot: treat both as rung-1 finishing work.
Raising the limit alone hides the stall instead of clearing it.
- **A mis-park is unparked and driven.** When the PR does not touch what its blocker names, or the
blocker holds only another part of a grouped update, run `unpark` and drive the PR. A blocker
that cannot be read, or a record that names none, never justifies unparking: re-verify or repair
the record instead.

**"Is someone actively working on it?" is decided from data, never by asking.** Treat a PR as actively
owned by someone else — and leave it alone this run — when any of these holds:

Expand Down Expand Up @@ -825,16 +903,19 @@ rung-one work — when current evidence shows any of these: a required check fai
never dispatched after its expected window; the branch is DIRTY/conflicting or behind with no live bot
update; the exact head is green but auto-merge was never armed or did not advance inside the normal
window; a merge-group was evicted or failed; or the ecosystem is pinned at its configured open-PR
limit by PRs in those states. Silence alone is not a stall, and an actively pending check is not a
failure. Queue-wide creation/merge history remains useful corroboration, but it is no longer required
when one PR's exact evidence already proves that it cannot finish itself.
limit, or one short of it, by PRs in those states or by parked PRs. Silence alone is not a stall,
and an actively pending check is not a failure. Queue-wide creation/merge history remains useful
corroboration, but it is no longer required when one PR's exact evidence already proves that it
cannot finish itself.

The survey emits `AUTOMATION-OWNED (SELF-PROGRESSING)` only with the positive evidence and timestamp
that justify it. It deepens every suspected or expired bot PR through the same current-head checks,
conflict, queue, and control joins as other rung-one work and emits `NEEDS-FIX`, `MERGE-READY`,
`ACTIVELY-OWNED`, or `QUERY-UNKNOWN` normally. A stalled bot PR counts against `nothing_on_fire` and
blocks issue descent until repaired, merged, or parked on a named live blocker — and a PR the
parked digest above reports `PARKED` is exactly that, so it no longer counts.
parked digest above reports `PARKED` is exactly that, so it no longer counts. A `STRANDED` row still
counts: its park holds, but its blocker or its next route is unowned work (see *A park is never a
resting place*).

Repair the root cause with the least invasive action that can finish the exact head: diagnose before
retrying; rerun only a demonstrated transient once; request the bot's update/rebase where that can
Expand Down
13 changes: 13 additions & 0 deletions .claude/guides/merge-policy.sensors.tsv
Original file line number Diff line number Diff line change
Expand Up @@ -107,3 +107,16 @@ MP-097 dependency-automation-and-programmed-bot-prs 🔴 **The exemption proves
MP-098 dependency-automation-and-programmed-bot-prs On a 404, `gh api` still prints the error body on none - -
MP-099 dependency-automation-and-programmed-bot-prs So a cask PR is the exception to "qualifying PRs none - -
MP-100 dependency-automation-and-programmed-bot-prs `RIPE` is necessary, not sufficient none - -
MP-101 you-own-every-pull-request-in-the-portfolio--whoever-authored-it A park is that state only while the parked digest reports the PR computational .claude/scripts/blocked-label-blocker-line-go/pulldigest.go "STRANDED"
MP-102 you-own-every-pull-request-in-the-portfolio--whoever-authored-it Its blocker is still owned work (*A park is never a resting place* below). none - -
MP-103 you-own-every-pull-request-in-the-portfolio--whoever-authored-it An authority park needs the route record too computational .claude/scripts/blocked-label-blocker-line-go/pulldigest.go return routeReason(line, o.today, o.strandedMaxAge)
MP-104 you-own-every-pull-request-in-the-portfolio--whoever-authored-it **A park is never a resting place** (agent-plugins#699 computational .claude/scripts/blocked-label-blocker-line-go/pulldigest.go "STRANDED"
MP-105 you-own-every-pull-request-in-the-portfolio--whoever-authored-it a parked PR is never merged while it is parked none - -
MP-106 you-own-every-pull-request-in-the-portfolio--whoever-authored-it Never close the PR to do it none - -
MP-107 you-own-every-pull-request-in-the-portfolio--whoever-authored-it The `next:` route is engineering you will do none - -
MP-108 you-own-every-pull-request-in-the-portfolio--whoever-authored-it A park never hands work to the maintainer none - -
MP-109 you-own-every-pull-request-in-the-portfolio--whoever-authored-it is only for a genuine question of direction you cannot settle none - -
MP-110 you-own-every-pull-request-in-the-portfolio--whoever-authored-it It is never a handoff and never a substitute for the work computational .claude/scripts/blocked-label-blocker-line-go/pulldigest.go return routeReason(line, o.today, o.strandedMaxAge)
MP-111 you-own-every-pull-request-in-the-portfolio--whoever-authored-it A blocker that cannot be read, or a record that names none, never justifies unparking none - -
MP-112 dependency-automation-and-programmed-bot-prs A `STRANDED` row still counts computational .claude/scripts/blocked-label-blocker-line-go/pulldigest.go labelled > parked
MP-113 you-own-every-pull-request-in-the-portfolio--whoever-authored-it Closing it otherwise is the separate decision that the release is unwanted none - -
3 changes: 3 additions & 0 deletions .claude/guides/work-selection.md
Original file line number Diff line number Diff line change
Expand Up @@ -487,6 +487,9 @@ immutable PR creation time when the start is unknown. `updatedAt` is activity, n
A PR reaches a terminal state when it is merged, parked on a named live-verified
blocker, or—when a stale draft is not worth reviving—closed with every still-valid finding re-filed
as an issue (an invalid or superseded finding may instead be closed with the reason recorded).
A park settles the PR, never its blocker: an in-portfolio blocker is finishing work at this rung,
and a parked dependency PR the parked digest reports `STRANDED` is still this rung's work (see
*A park is never a resting place* under [*You own EVERY pull request*](merge-policy.md#you-own-every-pull-request-in-the-portfolio--whoever-authored-it)).
Closing old work creates no intake credit: the lane's total open own-PR count must not rise while the
oldest cohort drains, and no replacement draft may be opened merely because an old one was disposed
of.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -916,7 +916,7 @@ func TestCLIComposerDigestAndContract(t *testing.T) {
// entrypoint: flag plumbing, the three row shapes and both exit codes.
const digestRecord = `> 🤖 Generated by the Agentic Engineer\n\n<!-- pr-blocker-record -->\n**Blocker:** o/r#7 | upstream | last-verified 2026-09-01: open`
digestPull := func(number int, state, comments string) string {
return fmt.Sprintf(`{"repo":"d","number":%d,"pull_request":{},"labels":[{"name":"blocked"}],%s"body":"x","comments":[%s]}`, number, state, comments)
return fmt.Sprintf(`{"repo":"d","number":%d,"pull_request":{},"user":{"login":"devantler"},"labels":[{"name":"blocked"}],%s"body":"x","comments":[%s]}`, number, state, comments)
}
comment := `{"user":{"login":"devantler"},"body":"` + digestRecord + `"}`
digest := payloadFile(t, "["+digestPull(1, `"blocker_state":"open",`, comment)+","+digestPull(2, `"blocker_state":"closed",`, comment)+","+digestPull(3, "", "")+"]")
Expand All @@ -939,7 +939,9 @@ func TestCLIComposerDigestAndContract(t *testing.T) {
// CONTRACT: the merge policy and the run procedure tell a run to read the
// digest and what each row means.
if parkRule != "" {
for _, token := range []string{"blocked-label-blocker-line.sh --org devantler-tech --parked-digest", "`PARKED <repo>#<n> [<note>] <blocker>`", "`ACTIONABLE <repo>#<n>", "`record=BLOCKER-CLOSED`", "`BLOCKER-SELF`", "never reads an authority blocker", "do not count it against `nothing_on_fire`", "`2` is UNKNOWN", "Only this digest makes a PR parked"} {
for _, token := range []string{"blocked-label-blocker-line.sh --org devantler-tech --parked-digest", "`PARKED <repo>#<n> [<note>] <blocker>`", "`ACTIONABLE <repo>#<n>", "`record=BLOCKER-CLOSED`", "`BLOCKER-SELF`", "never reads an authority blocker", "do not count it against `nothing_on_fire`", "`2` is UNKNOWN", "Only this digest makes a PR parked",
// A park is owned work, never a resting place (devantler-tech/agent-plugins#699).
"`STRANDED <repo>#<n> reason=<reason> age=<n>d <blocker>`", "`reason=UNCLAIMED`", "`reason=NO-ROUTE`", "`reason=ROUTE-LAPSED`", "`tried: <the route and what it showed>`", "`next: <the engineering route you take next>`", "`re-check <YYYY-MM-DD>`", "a maintainer ask never pauses the work", "**Ownership stays with the agent**", "no bound or timer in these rules makes", "handoff and never a substitute for the work", "**A park is never a resting place**", "Its blocker is still owned work", "Raising the limit alone hides the stall", "**A mis-park is unparked and driven.**"} {
assert(t, "the parked-PR rule states: "+token, strings.Contains(parkRule, token), "not found in the rule paragraph")
}
for _, token := range []string{"--parked-digest", "BLOCKER-CLOSED", "CHECKED"} {
Expand All @@ -948,6 +950,8 @@ func TestCLIComposerDigestAndContract(t *testing.T) {
}
assert(t, "the run procedure runs the parked digest after the survey",
strings.Contains(readGuide(t, "skills/portfolio-maintenance/SKILL.md"), "blocked-label-blocker-line.sh --org devantler-tech --parked-digest"), "command not found in the run procedure")
assert(t, "the run procedure reads a STRANDED row as rung-1 work",
strings.Contains(flat(readGuide(t, "skills/portfolio-maintenance/SKILL.md")), "An `ACTIONABLE` or `STRANDED` row is rung-1 work this run"), "STRANDED is not work in the run procedure")
}

const (
Expand Down
Loading
Loading