From d865be9f9066bd90d6467e9b6303546907ba400e Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Fri, 13 Nov 2026 00:54:58 +0100 Subject: [PATCH 1/5] feat(agentic-engineering): make a parked PR owned work, never a terminal state Dependency-update PRs stranded for weeks once a deployment parked them: runs read the park as finished, nobody worked the blocker or re-checked the upstream release it waited on, and parked PRs filled an ecosystem's open-PR limit so no new update could open. The agent definition, the portfolio-maintenance run loop and its PR-driving procedure now say: an in-portfolio blocker is finishing work, claimed and worked ahead of new pulls; an upstream blocker is re-checked at least every 7 days with an engineering route weighed each time; a dependency PR parked for 14 days gets a recorded decision (route or why none, the upstream event awaited, a re-check date) and reaches the maintainer once past 30 days; an update ecosystem at or near its open-PR limit with parked PRs is a stall; and a mis-park is unparked and driven. The Cadence can set other bounds. The surveyor reports parked/blocker/decision facts, unknown when unreadable. A new contract test pins the clauses with mutation controls. Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 2 +- .github/plugin/marketplace.json | 2 +- .../.claude-plugin/plugin.json | 2 +- .../.codex-plugin/plugin.json | 2 +- plugins/agentic-engineering/CHANGELOG.md | 16 ++ .../agents/agentic-engineer.agent.md | 8 +- .../agents/portfolio-surveyor.agent.md | 11 +- plugins/agentic-engineering/plugin.json | 2 +- .../provider-neutral.desired-state.json | 4 +- .../parked-pr-ownership-contract.test.sh | 166 ++++++++++++++++++ .../skills/portfolio-maintenance/SKILL.md | 7 +- .../references/driving-prs.md | 39 ++++ 12 files changed, 250 insertions(+), 11 deletions(-) create mode 100755 plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c5bfb343..082ae89a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -20,7 +20,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.6.8", + "version": "7.7.0", "source": "./plugins/agentic-engineering" }, { diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index c5bfb343..082ae89a 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -20,7 +20,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.6.8", + "version": "7.7.0", "source": "./plugins/agentic-engineering" }, { diff --git a/plugins/agentic-engineering/.claude-plugin/plugin.json b/plugins/agentic-engineering/.claude-plugin/plugin.json index 87743eb6..b597feab 100644 --- a/plugins/agentic-engineering/.claude-plugin/plugin.json +++ b/plugins/agentic-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.6.8", + "version": "7.7.0", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/agentic-engineering/.codex-plugin/plugin.json b/plugins/agentic-engineering/.codex-plugin/plugin.json index 751d8250..79deb5b1 100644 --- a/plugins/agentic-engineering/.codex-plugin/plugin.json +++ b/plugins/agentic-engineering/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.6.8", + "version": "7.7.0", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/agentic-engineering/CHANGELOG.md b/plugins/agentic-engineering/CHANGELOG.md index 8f92ccbf..9e4aff58 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog — `agentic-engineering` +## 7.7.0 — 2026-11-13 + +**Added** — a parked PR is owned work, never a terminal state. The `agentic-engineer` definition, +the `portfolio-maintenance` run loop and its PR-driving procedure now say what a run does with a PR +parked through the deployment's blocked-work mechanism. An in-portfolio blocker is finishing work, +claimed and worked ahead of new pulls. An upstream blocker is re-checked against live upstream +state at least every 7 days, and each check weighs an engineering route: adapt, isolate or replace +the dependency, contribute upstream, or split out only the blocked part of a grouped update. A +dependency-update PR parked for 14 days gets a recorded decision: the route taken or why there is +none, the exact upstream event it awaits, and a re-check date. Past 30 days it goes to the +maintainer once. An update ecosystem whose open-PR limit is filled by parked PRs is a stall, and a +PR that does not depend on its named blocker is unparked and driven. The **Cadence** can set other +bounds. The `portfolio-surveyor` reports `parked`, `blocker` and `decision` facts for each parked +candidate PR, and `unknown` when it cannot read them. `parked-pr-ownership-contract.test.sh` pins +the clauses. + ## 7.6.8 — 2026-11-12 **Changed** — sync `code-review` from `https://github.com/coderabbitai/skills` at `refs/tags/v1.2.2`. diff --git a/plugins/agentic-engineering/agents/agentic-engineer.agent.md b/plugins/agentic-engineering/agents/agentic-engineer.agent.md index ce411b4d..31bbf8fd 100644 --- a/plugins/agentic-engineering/agents/agentic-engineer.agent.md +++ b/plugins/agentic-engineering/agents/agentic-engineer.agent.md @@ -140,7 +140,13 @@ merge path; a shared definition's portfolio-owned upstream remains on that portf with the pentad clear is driven to merge with the mechanics the **Trust gate** names for that author and repo; your own promoted PRs follow the same path, including your own definition PRs. Bot dependency-update PRs are first-priority trusted work, driven green like any other — never - dismissed as self-managing. Every dependency update is read as a release range, regardless of + dismissed as self-managing. **Parking is not finishing:** a PR parked through the deployment's + blocked-work mechanism stays owned work. Work its blocker (an in-portfolio blocker is finishing + work, ahead of new pulls; an upstream one is re-checked on a cadence, with an engineering route + considered each time), give a dependency PR parked past its bound a recorded decision and re-check + date, treat an update ecosystem whose open-PR limit is filled by parked PRs as a stall, and unpark + and drive a mis-park. The `portfolio-maintenance` PR-driving procedure holds the complete rules. + Every dependency update is read as a release range, regardless of author: before promoting or merging one, complete and record the bundled `product-engineering` skill's upstream release review. Follow that procedure's product-applicability decisions: assess every announced change and implement only the fixes, diff --git a/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md b/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md index d69e29de..bf54bc05 100644 --- a/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md +++ b/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md @@ -311,6 +311,15 @@ included**, automation-owned dependency PRs excluded — report: - **(d) merge conflicts / behind-base state.** - **(e) green-review state** — see below. +**Park facts, for a parked PR.** A PR the consumer parked through its blocked-work mechanism is +still a candidate, never settled. When a candidate carries the consumer's blocked-work label, also +report `parked=`, `blocker=` as the +consumer's blocked-work record on the PR names it, and `decision=|none`. Read the date from the PR's own label events and the record from the PR +itself. A read that fails, or a record you cannot parse, reports that field as `unknown`, never a +guessed date or `none`. The orchestrator applies its PR-driving procedure's parked-PR rules to +these facts; never omit a parked PR from the digest, or classify it as finished, because it is parked. + A PR is review-ready only when current-head body findings **and** unresolved threads are 0, there is no ordinary failing check (a `managed-failing` check alone does not count), it is not conflicting, and it carries ≥1 green review. `mergeState` stays an independent merge gate. @@ -916,7 +925,7 @@ budget: graphql=→/ · core=→/[ · EXHA - REPO-SET-DRIFT — live set vs Portfolio map: new= · missing/renamed= · map-drift= → orchestrator reconciles (archived-marked rows exempt) - : CI red on @ — (), event=, path=, created=, run=, attempt= # judged at that branch's current head; routing fields come directly from the classifier; omit the repo when green - # "" — <exact bot identity> → AUTOMATION-OWNED (NO-ACTION) -- <repo> #<n> (trusted bot, draft) — pentad: checks=<green|failing:X|managed-failing:X|failing:X+managed-failing:Y>, unresolved=<n|unknown>, body_findings=<n>@<sha>|<n>-stale@<sha>|0-resolved@<sha>, green_review=<…>, review_reservation=<…>, review_pending=<…>, review_progress=<…>, rd=<APPROVED|CHANGES_REQUESTED:<author>@<sha>|none>, mergeState=<…> → REVIEW-READY | NEEDS-FIX | STALE-CR-DISMISSAL +- <repo> #<n> (trusted bot, draft) — pentad: checks=<green|failing:X|managed-failing:X|failing:X+managed-failing:Y>, unresolved=<n|unknown>, body_findings=<n>@<sha>|<n>-stale@<sha>|0-resolved@<sha>, green_review=<…>, review_reservation=<…>, review_pending=<…>, review_progress=<…>, rd=<APPROVED|CHANGES_REQUESTED:<author>@<sha>|none>, mergeState=<…>[, parked=<date|unknown>, blocker=<…|unknown>, decision=<date|none|unknown>] → REVIEW-READY | NEEDS-FIX | STALE-CR-DISMISSAL - <repo> #<n> (trusted bot, non-draft) — pentad: <same fields> → MERGE-READY | NEEDS-FIX | STALE-CR-DISMISSAL - <repo> #<n> "<title>" — maintainer login, draft=<true|false> → OWNERSHIP-UNVERIFIED: branch=<headRefName>, disclosure=<routine|interactive|none>, pentad=<…>, review_reservation=<…>, review_pending=<…>, review_progress=<…> → NEEDS-FIX | CLEAR (pentad disposition only — orchestrator applies creation-record test before action; never MERGE-READY, never asserted mine) - <repo>: untriaged → issues #a,#b · PRs #c | stale (>14d) → #d diff --git a/plugins/agentic-engineering/plugin.json b/plugins/agentic-engineering/plugin.json index 87743eb6..b597feab 100644 --- a/plugins/agentic-engineering/plugin.json +++ b/plugins/agentic-engineering/plugin.json @@ -1,7 +1,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.6.8", + "version": "7.7.0", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/agentic-engineering/resources/provider-neutral.desired-state.json b/plugins/agentic-engineering/resources/provider-neutral.desired-state.json index d86f4135..632cbe08 100644 --- a/plugins/agentic-engineering/resources/provider-neutral.desired-state.json +++ b/plugins/agentic-engineering/resources/provider-neutral.desired-state.json @@ -42,7 +42,7 @@ "executable": true } ], - "entrypointSha256": "01bacbbd7b03486ab35004f11461dfedec62a575d3c126f6fe5feab29ea36cad", + "entrypointSha256": "6c6d2d0e6f71c0d93d27e2a0c34bc6ef2894b4aefac289256f9d76c428bd05a7", "updatePolicy": "latest-reviewed-default-branch", "providerPolicy": "neutral", "refreshTiming": "before-starting-each-run", @@ -76,7 +76,7 @@ "portfolio-surveyor": { "enabled": true, "mode": "delegated-read-only", - "definitionSha256": "718e2058a2a547e108e807fabd53ccf7cf7ce7a21be37d7045ac4ba7c2d6f184" + "definitionSha256": "cb23eff17c5ff48c189aa208128455fd1d558868373d838f69c8d49285447a9c" }, "agent-improver": { "enabledWhen": "Both optional consumer contract sections are present", diff --git a/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh new file mode 100755 index 00000000..dd95d4c5 --- /dev/null +++ b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh @@ -0,0 +1,166 @@ +#!/usr/bin/env bash +# Contract test: a parked PR is owned work, never a terminal state. +# +# Dependency-update PRs stranded for weeks once a deployment parked them on a blocker: each run read +# the park as finished, nobody worked the blocker or re-checked the upstream it waited on, and nine +# parked PRs filled one ecosystem's open-PR limit so no new update could open. The role already said +# bot PRs are first-priority work; nothing said a park stays owned. These clauses say it in the three +# places a run reads it — the agent definition, the PR-driving procedure the skill links, and the +# surveyor that reports parked PRs — and each is removed from a copy to prove its assertion fires. +set -Eeuo pipefail + +plugin_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +agent="$plugin_root/agents/agentic-engineer.agent.md" +surveyor="$plugin_root/agents/portfolio-surveyor.agent.md" +skill_dir="$plugin_root/skills/portfolio-maintenance" +tmp="$(mktemp -d)" +# Bash 3.2 can report an errexit abort as success once an EXIT trap has run, so the trap refuses to +# exit 0 unless the script reached its final line. +completed=0 +trap 'rm -rf "$tmp"; [ "$completed" = 1 ] || exit 1' EXIT + +agent_clauses=( + "parking is not finishing: a pr parked through the deployment's blocked-work mechanism stays owned work." + "an in-portfolio blocker is finishing work, ahead of new pulls" + "an upstream one is re-checked on a cadence, with an engineering route considered each time" + "give a dependency pr parked past its bound a recorded decision and re-check date" + "treat an update ecosystem whose open-pr limit is filled by parked prs as a stall" + "unpark and drive a mis-park." +) +skill_clauses=( + # The run loop's own summary, so a run that never opens the reference still meets the rule. + "a parked pr is not finished: its blocker is owned work" + "work the in-portfolio blocker behind every parked pr" + # The complete rule, in the PR-driving procedure the skill links. + "a parked pr is not a resting place." + "the blocker a park names is owned work, and these rules apply to every parked pr on every run that drives prs:" + "an in-portfolio blocker is finishing work." + "an unclaimed in-portfolio blocker behind a parked pr is a finding, never a wait." + "make or escalate that decision, and never resume fixing its findings one by one." + "an upstream blocker is re-checked, not waited on." + "at least every 7 days unless the cadence names another interval" + "each check also weighs an engineering route instead of only waiting:" + "or split or ignore only the blocked part of a grouped update, so the rest merges now." + "once it has been parked for 14 days, unless the cadence names another bound" + "plus the exact upstream event it awaits" + "a missing or lapsed decision makes the pr actionable again." + "past a longer bound, 30 days unless the cadence names another, raise it once through the deployment's maintainer channels" + "an update ecosystem at or near its open-pr limit is stalled." + "raising the limit alone hides the stall instead of clearing it." + "a mis-park is unparked and driven. at every check, confirm the pr really depends on its named blocker:" + "when its park facts (when it was parked, its blocker, its latest decision) cannot be read, the pr is unknown, never settled." +) +surveyor_clauses=( + "a pr the consumer parked through its blocked-work mechanism is still a candidate, never settled." + "reports that field as \`unknown\`, never a guessed date or \`none\`." + "never omit a parked pr from the digest, or classify it as finished, because it is parked." + "parked=<date|unknown>" +) +# A sentence that would make any of the three read a park as settled. +forbidden_clauses=( + "a parked pr is a terminal state" + "parked prs are finished" +) + +normalize() { + LC_ALL=C awk '{ + line=tolower($0) + gsub(/\*/, "", line) + gsub(/[[:space:]]+/, " ", line) + gsub(/^[[:space:]]+|[[:space:]]+$/, "", line) + if (line != "") printf "%s ", line + } + # One terminated line, so an awk pass that removes nothing reproduces it byte for byte and the + # "found nothing to remove" guard below can actually fire. + END { printf "\n" }' "$1" +} + +# check <file> <clause>... — exit 0 when every clause is present and no forbidden one is. +check() { + local file="$1" text clause + shift + text="$(normalize "$file")" + [ -n "$text" ] || return 1 + for clause in "$@"; do + [[ $text == *"$clause"* ]] || return 1 + done + for clause in "${forbidden_clauses[@]}"; do + [[ $text != *"$clause"* ]] || return 1 + done +} + +# The skill keeps a summary and links the complete rung in references/driving-prs.md. Check the text +# an agent reads by following that link: the skill with the reference inserted after the first line +# that links it. A dropped link or an emptied reference removes the clauses, so the check fails closed. +linked_skill() { # skill-dir output reference + LC_ALL=C awk -v dir="$1" -v ref="$3" ' + { + print + if (!done && index($0, "](" ref ")")) { + while ((getline line < (dir "/" ref)) > 0) print line + close(dir "/" ref) + done = 1 + } + } + ' "$1/SKILL.md" >"$2" +} + +fail=0 +for f in "$agent" "$surveyor" "$skill_dir/SKILL.md" "$skill_dir/references/driving-prs.md"; do + [ -r "$f" ] || { echo "cannot read $f" >&2; exit 1; } +done +linked_skill "$skill_dir" "$tmp/linked-skill.md" references/driving-prs.md +grep -qF "A parked PR is not a resting place." "$tmp/linked-skill.md" || { + echo " ✗ SKILL.md no longer links references/driving-prs.md, so the linked text lacks the rule" >&2 + exit 1 +} + +# surface <label> <file> <clause>... +surface() { + local label="$1" file="$2" clause + shift 2 + local -a clauses=("$@") + if check "$file" "${clauses[@]}"; then + echo " ✓ $label says a parked PR stays owned work" + else + echo " ✗ $label must say a parked PR stays owned work (missing clause, or a forbidden one present)" >&2 + fail=1 + fi + # Mutation cases: the text with one clause removed must fail. Prose wraps, so each clause is removed + # from the normalised text, not the file. + normalize "$file" >"$tmp/normalized.md" + for clause in "${clauses[@]}"; do + awk -v clause="$clause" '{ + position = index($0, clause) + if (position > 0) $0 = substr($0, 1, position - 1) substr($0, position + length(clause)) + print + }' "$tmp/normalized.md" >"$tmp/mutant.md" + if cmp -s "$tmp/normalized.md" "$tmp/mutant.md"; then + echo " ✗ $label: mutation found nothing to remove for: $clause" >&2 + fail=1 + elif check "$tmp/mutant.md" "${clauses[@]}"; then + echo " ✗ $label: check passed with a clause removed: $clause" >&2 + fail=1 + else + echo " ✓ $label: removing a clause fails: ${clause:0:60}…" + fi + done + # A forbidden sentence added to the real text must fail, for the right reason: every required + # clause is still present. + for clause in "${forbidden_clauses[@]}"; do + { cat "$tmp/normalized.md"; printf '%s\n' "$clause"; } >"$tmp/forbidden.md" + if check "$tmp/forbidden.md" "${clauses[@]}"; then + echo " ✗ $label: check passed with a forbidden clause added: $clause" >&2 + fail=1 + else + echo " ✓ $label: adding a forbidden clause fails: $clause" + fi + done +} + +surface "agentic-engineer" "$agent" "${agent_clauses[@]}" +surface "portfolio-maintenance (with driving-prs.md)" "$tmp/linked-skill.md" "${skill_clauses[@]}" +surface "portfolio-surveyor" "$surveyor" "${surveyor_clauses[@]}" + +completed=1 +exit "$fail" diff --git a/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md b/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md index 2b5a8378..051793c5 100644 --- a/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md +++ b/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md @@ -130,7 +130,7 @@ actionable work remains, **within the per-run budget and stop conditions the dep section sets** — an unattended run ends when actionable work is exhausted or blocked, or when that budget is spent, never merely after a few items. **Stop starting, start finishing:** before opening any new draft, drive every own in-flight PR to merged (self-promote when genuine readiness holds) or keep it draft with -the missing readiness condition named — a readiness-proven merge is the deliverable; a half-finished +the missing readiness condition named, and work the in-portfolio blocker behind every parked PR — a readiness-proven merge is the deliverable; a half-finished draft is unfinished work to clear first. **Operate (keep it healthy) — always before advancing:** @@ -141,7 +141,10 @@ draft is unfinished work to clear first. trusted-author, non-draft PR whose current-head pentad is clear with the **Trust gate**'s mechanics, revalidating genuine readiness at the current head immediately before every merge. Keep every open own/trusted PR hygienic while it waits, dependency PRs included, and complete the - upstream release review before promoting or merging a dependency update. Never run or auto-merge + upstream release review before promoting or merging a dependency update. A parked PR is not + finished: its blocker is owned work, a dependency PR parked past its bound needs a recorded + decision, an update ecosystem whose open-PR limit is filled by parked PRs is a stall, and a + mis-park is unparked and driven. Never run or auto-merge an external contributor's branch. **Read [the PR-driving procedure](references/driving-prs.md) before driving, promoting or merging any PR**; it is the complete rung. 3. **Contributor-facing** — triage and label new issues and PRs; answer the oldest un-commented item. diff --git a/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md b/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md index 3ab9946a..823e51e3 100644 --- a/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md +++ b/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md @@ -52,3 +52,42 @@ keeps only its summary. readback or concurrent movement remain named blockers, never inferred green. The **Trust gate** still governs branch execution and writes; none of these routes permits running untrusted branch code locally. Deliberately rejecting an unwanted update is a separate decision. + + **A parked PR is not a resting place.** Parking a PR through the deployment's blocked-work + mechanism records why it cannot merge yet. It never settles the PR: a run that counts parked PRs + as finished lets them strand for weeks while nobody works what holds them. The blocker a park + names is owned work, and these rules apply to every parked PR on every run that drives PRs: + - **An in-portfolio blocker is finishing work.** When the blocker is an issue, PR or decision + inside the Portfolio map, rank it with your in-flight PRs, ahead of any new pull: claim it + through the deployment's claim mechanism and work it to its own terminal state. An unclaimed + in-portfolio blocker behind a parked PR is a finding, never a wait. For a PR parked on a review + that did not converge, the blocker is the scope or design decision its record names: make or + escalate that decision, and never resume fixing its findings one by one. + - **An upstream blocker is re-checked, not waited on.** Re-verify it against live upstream state + (releases, tags, and the upstream issue or PR) at least every 7 days unless the **Cadence** + names another interval, and on every re-check date the park records. Each check also weighs an + engineering route instead of only waiting: adapt the product to the new version; isolate or + replace the conflicting dependency; contribute the fix upstream under the egress and + upstream-contribution rules; or split or ignore only the blocked part of a grouped update, so + the rest merges now. A route taken is ordinary work under the normal readiness gates. + - **A dependency-update PR parked past its bound needs a recorded decision.** Once it has been + parked for 14 days, unless the **Cadence** names another bound, record on the PR the route you + took, or why no route exists, plus the exact upstream event it awaits (a named release or a + merged upstream change) and the next re-check date. A missing or lapsed decision makes the PR + actionable again. Past a longer bound, 30 days unless the **Cadence** names another, raise it + once through the deployment's **Maintainer channels** with that record, and never as a + repeated ask. + - **An update ecosystem at or near its open-PR limit is stalled.** When the open PRs of one + dependency-update configuration (one package manager and directory) reach its configured + open-PR limit, or are one short of it, and any of them is parked, new updates stop opening, + security fixes included. Treat that as finishing work: unblock, combine or narrow the parked + updates (for example, ignore only the blocked version range and record that on the blocker) so + slots free up. Raising the limit alone hides the stall instead of clearing it. + - **A mis-park is unparked and driven.** At every check, confirm the PR really depends on its + named blocker: the change touches what the blocker names, and the blocker is still open and + still holds. A PR that does not depend on it (the wrong blocker, a blocker already closed or + resolved, or one that holds only another part of a grouped update) is unparked through the + same mechanism and driven like any other PR. + + A parked PR never leaves the survey. When its park facts (when it was parked, its blocker, its + latest decision) cannot be read, the PR is unknown, never settled. From 704fabc5e399185eee945df47427811ab22a98e9 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm <nikolaiemildamm@icloud.com> Date: Fri, 13 Nov 2026 01:14:33 +0100 Subject: [PATCH 2/5] fix(agentic-engineering): keep ownership of a long-parked PR with the agent The maintainer corrected the rule on 2026-11-13: a dependency PR parked past the bound is not handed to him. Drop the 30-day escalation. Past the bound the agent takes engineering routes itself (adapt, fork or patch, isolate or replace, contribute upstream, split the update) and keeps taking them, recording what it tried, the next route and when it looks again. A maintainer-ask is only for a genuine question of direction, never a handoff: it states the default the agent will act on, and the work continues meanwhile. No timer makes contacting the maintainer the outcome. The contract test pins the new clauses and forbids the escalation sentence. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- plugins/agentic-engineering/CHANGELOG.md | 17 ++++++---- .../agents/agentic-engineer.agent.md | 8 +++-- .../provider-neutral.desired-state.json | 2 +- .../parked-pr-ownership-contract.test.sh | 23 +++++++++---- .../skills/portfolio-maintenance/SKILL.md | 7 ++-- .../references/driving-prs.md | 33 +++++++++++-------- 6 files changed, 56 insertions(+), 34 deletions(-) diff --git a/plugins/agentic-engineering/CHANGELOG.md b/plugins/agentic-engineering/CHANGELOG.md index 9e4aff58..8991494c 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -6,13 +6,16 @@ the `portfolio-maintenance` run loop and its PR-driving procedure now say what a run does with a PR parked through the deployment's blocked-work mechanism. An in-portfolio blocker is finishing work, claimed and worked ahead of new pulls. An upstream blocker is re-checked against live upstream -state at least every 7 days, and each check weighs an engineering route: adapt, isolate or replace -the dependency, contribute upstream, or split out only the blocked part of a grouped update. A -dependency-update PR parked for 14 days gets a recorded decision: the route taken or why there is -none, the exact upstream event it awaits, and a re-check date. Past 30 days it goes to the -maintainer once. An update ecosystem whose open-PR limit is filled by parked PRs is a stall, and a -PR that does not depend on its named blocker is unparked and driven. The **Cadence** can set other -bounds. The `portfolio-surveyor` reports `parked`, `blocker` and `decision` facts for each parked +state at least every 7 days, and each check weighs an engineering route: adapt, fork or patch, +isolate or replace the dependency, contribute upstream, or split out only the blocked part of a +grouped update. Once a dependency-update PR has been parked for 14 days, waiting stops counting as a +route. The agent takes engineering routes itself and keeps taking them, recording on the PR what it +tried, the next route, and when it will look again. Ownership stays with the agent. A park never +hands work to the maintainer, and no bound makes contacting the maintainer the outcome. A +maintainer-ask is only for a genuine question of direction, with the default the agent will act on, +and the work continues meanwhile. An update ecosystem whose open-PR limit is filled by parked PRs +is a stall, and a PR that does not depend on its named blocker is unparked and driven. The +**Cadence** can set another bound. The `portfolio-surveyor` reports `parked`, `blocker` and `decision` facts for each parked candidate PR, and `unknown` when it cannot read them. `parked-pr-ownership-contract.test.sh` pins the clauses. diff --git a/plugins/agentic-engineering/agents/agentic-engineer.agent.md b/plugins/agentic-engineering/agents/agentic-engineer.agent.md index 31bbf8fd..70a87cdc 100644 --- a/plugins/agentic-engineering/agents/agentic-engineer.agent.md +++ b/plugins/agentic-engineering/agents/agentic-engineer.agent.md @@ -143,9 +143,11 @@ merge path; a shared definition's portfolio-owned upstream remains on that portf dismissed as self-managing. **Parking is not finishing:** a PR parked through the deployment's blocked-work mechanism stays owned work. Work its blocker (an in-portfolio blocker is finishing work, ahead of new pulls; an upstream one is re-checked on a cadence, with an engineering route - considered each time), give a dependency PR parked past its bound a recorded decision and re-check - date, treat an update ecosystem whose open-PR limit is filled by parked PRs as a stall, and unpark - and drive a mis-park. The `portfolio-maintenance` PR-driving procedure holds the complete rules. + considered each time). Unblock a dependency PR parked past its bound by engineering routes you + take yourself, recording what you tried and the next route. Treat an update ecosystem whose + open-PR limit is filled by parked PRs as a stall, and unpark and drive a mis-park. Ownership stays + with you: a park never hands work to the maintainer, and no timer makes contacting the maintainer + the outcome. The `portfolio-maintenance` PR-driving procedure holds the complete rules. Every dependency update is read as a release range, regardless of author: before promoting or merging one, complete and record the bundled `product-engineering` skill's upstream release review. Follow that procedure's diff --git a/plugins/agentic-engineering/resources/provider-neutral.desired-state.json b/plugins/agentic-engineering/resources/provider-neutral.desired-state.json index 632cbe08..1d20ec51 100644 --- a/plugins/agentic-engineering/resources/provider-neutral.desired-state.json +++ b/plugins/agentic-engineering/resources/provider-neutral.desired-state.json @@ -42,7 +42,7 @@ "executable": true } ], - "entrypointSha256": "6c6d2d0e6f71c0d93d27e2a0c34bc6ef2894b4aefac289256f9d76c428bd05a7", + "entrypointSha256": "214c774907c50a1b491f1f05cbce34d6398240ed558e2291cb35d47ce858ed64", "updatePolicy": "latest-reviewed-default-branch", "providerPolicy": "neutral", "refreshTiming": "before-starting-each-run", diff --git a/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh index dd95d4c5..5978d353 100755 --- a/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh +++ b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh @@ -23,28 +23,35 @@ agent_clauses=( "parking is not finishing: a pr parked through the deployment's blocked-work mechanism stays owned work." "an in-portfolio blocker is finishing work, ahead of new pulls" "an upstream one is re-checked on a cadence, with an engineering route considered each time" - "give a dependency pr parked past its bound a recorded decision and re-check date" + "unblock a dependency pr parked past its bound by engineering routes you take yourself, recording what you tried and the next route." + "ownership stays with you: a park never hands work to the maintainer, and no timer makes contacting the maintainer the outcome." "treat an update ecosystem whose open-pr limit is filled by parked prs as a stall" "unpark and drive a mis-park." ) skill_clauses=( # The run loop's own summary, so a run that never opens the reference still meets the rule. "a parked pr is not finished: its blocker is owned work" + "ownership never moves to the maintainer." "work the in-portfolio blocker behind every parked pr" # The complete rule, in the PR-driving procedure the skill links. "a parked pr is not a resting place." "the blocker a park names is owned work, and these rules apply to every parked pr on every run that drives prs:" "an in-portfolio blocker is finishing work." "an unclaimed in-portfolio blocker behind a parked pr is a finding, never a wait." - "make or escalate that decision, and never resume fixing its findings one by one." + "make that decision yourself, and never resume fixing its findings one by one." "an upstream blocker is re-checked, not waited on." "at least every 7 days unless the cadence names another interval" "each check also weighs an engineering route instead of only waiting:" "or split or ignore only the blocked part of a grouped update, so the rest merges now." - "once it has been parked for 14 days, unless the cadence names another bound" - "plus the exact upstream event it awaits" - "a missing or lapsed decision makes the pr actionable again." - "past a longer bound, 30 days unless the cadence names another, raise it once through the deployment's maintainer channels" + "once it has been parked for 14 days, unless the cadence names another bound, waiting is no longer a route." + "take an engineering route yourself, and keep taking them until the pr merges:" + "record on the pr what you tried and what it showed, the next route you will take," + "a missing or lapsed record makes the pr actionable again." + # The maintainer owns direction, not the work (maintainer, 2026-11-13): no bound hands it over. + "ownership stays with you." + "no timer or bound makes contacting the maintainer the outcome." + "only for a genuine question of direction you cannot settle on your own, and never to ask about what you can do yourself." + "such an ask is never a handoff and never a substitute for the work: state the default you will act on if no answer comes, and keep working the routes meanwhile." "an update ecosystem at or near its open-pr limit is stalled." "raising the limit alone hides the stall instead of clearing it." "a mis-park is unparked and driven. at every check, confirm the pr really depends on its named blocker:" @@ -56,10 +63,12 @@ surveyor_clauses=( "never omit a parked pr from the digest, or classify it as finished, because it is parked." "parked=<date|unknown>" ) -# A sentence that would make any of the three read a park as settled. +# A sentence that would make any of the three read a park as settled, or hand it to the maintainer. forbidden_clauses=( "a parked pr is a terminal state" "parked prs are finished" + "raise it once through the deployment's maintainer channels" + "past a longer bound" ) normalize() { diff --git a/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md b/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md index 051793c5..27d8a41a 100644 --- a/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md +++ b/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md @@ -142,9 +142,10 @@ draft is unfinished work to clear first. mechanics, revalidating genuine readiness at the current head immediately before every merge. Keep every open own/trusted PR hygienic while it waits, dependency PRs included, and complete the upstream release review before promoting or merging a dependency update. A parked PR is not - finished: its blocker is owned work, a dependency PR parked past its bound needs a recorded - decision, an update ecosystem whose open-PR limit is filled by parked PRs is a stall, and a - mis-park is unparked and driven. Never run or auto-merge + finished: its blocker is owned work, a dependency PR parked past its bound is unblocked by + engineering routes you take yourself, an update ecosystem whose open-PR limit is filled by parked + PRs is a stall, and a mis-park is unparked and driven. Ownership never moves to the maintainer. + Never run or auto-merge an external contributor's branch. **Read [the PR-driving procedure](references/driving-prs.md) before driving, promoting or merging any PR**; it is the complete rung. 3. **Contributor-facing** — triage and label new issues and PRs; answer the oldest un-commented item. diff --git a/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md b/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md index 823e51e3..da898770 100644 --- a/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md +++ b/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md @@ -61,22 +61,29 @@ keeps only its summary. inside the Portfolio map, rank it with your in-flight PRs, ahead of any new pull: claim it through the deployment's claim mechanism and work it to its own terminal state. An unclaimed in-portfolio blocker behind a parked PR is a finding, never a wait. For a PR parked on a review - that did not converge, the blocker is the scope or design decision its record names: make or - escalate that decision, and never resume fixing its findings one by one. + that did not converge, the blocker is the scope or design decision its record names: make that + decision yourself, and never resume fixing its findings one by one. - **An upstream blocker is re-checked, not waited on.** Re-verify it against live upstream state (releases, tags, and the upstream issue or PR) at least every 7 days unless the **Cadence** names another interval, and on every re-check date the park records. Each check also weighs an - engineering route instead of only waiting: adapt the product to the new version; isolate or - replace the conflicting dependency; contribute the fix upstream under the egress and - upstream-contribution rules; or split or ignore only the blocked part of a grouped update, so - the rest merges now. A route taken is ordinary work under the normal readiness gates. - - **A dependency-update PR parked past its bound needs a recorded decision.** Once it has been - parked for 14 days, unless the **Cadence** names another bound, record on the PR the route you - took, or why no route exists, plus the exact upstream event it awaits (a named release or a - merged upstream change) and the next re-check date. A missing or lapsed decision makes the PR - actionable again. Past a longer bound, 30 days unless the **Cadence** names another, raise it - once through the deployment's **Maintainer channels** with that record, and never as a - repeated ask. + engineering route instead of only waiting: adapt the product to the new version; fork or patch + the dependency; isolate or replace the conflicting dependency; contribute the fix upstream + under the egress and upstream-contribution rules; or split or ignore only the blocked part of a + grouped update, so the rest merges now. A route taken is ordinary work under the normal + readiness gates. + - **Past its bound, a parked dependency-update PR is yours to unblock by engineering.** Once it + has been parked for 14 days, unless the **Cadence** names another bound, waiting is no longer a + route. Take an engineering route yourself, and keep taking them until the PR merges: adapt the + product, fork or patch the dependency, isolate or replace the conflicting dependency, + contribute upstream, or split the update so the unblocked part merges. Record on the PR what + you tried and what it showed, the next route you will take, and the date you will look again, + at most one bound ahead. A missing or lapsed record makes the PR actionable again. + - **Ownership stays with you.** You own the code and its dependency updates, never the + maintainer. A park never hands work to the maintainer, and no timer or bound makes contacting + the maintainer the outcome. Use the deployment's **Maintainer channels** only for a genuine + question of direction you cannot settle on your own, and never to ask about what you can do + yourself. Such an ask is never a handoff and never a substitute for the work: state the default + you will act on if no answer comes, and keep working the routes meanwhile. - **An update ecosystem at or near its open-PR limit is stalled.** When the open PRs of one dependency-update configuration (one package manager and directory) reach its configured open-PR limit, or are one short of it, and any of them is parked, new updates stop opening, From 9d1526e0317b88f23a0b4ce7a1b0930a8c9c3101 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm <nikolaiemildamm@icloud.com> Date: Fri, 13 Nov 2026 01:25:14 +0100 Subject: [PATCH 3/5] fix(agentic-engineering): close the review round's gaps in the parked-PR rule From the local review round on #699: - automation-owned PRs stay outside the parked-PR rules, as the survey already leaves them; - the surveyor judges a park only from the PR's own complete label list against the park label the Portfolio map names, never a census row, and measures age from the first park; - `blocker=decision` covers a scope or design blocker, and a blocker that cannot be read or a record that names none never justifies unparking; - a lapsed route record makes the next route finishing work, never lifts the park or merge hold; - an ignore is recorded on its blocker and removed when it clears; - Dependabot security updates have their own limit, so a version-update stall does not block them; - summaries match the full stall rule, every PR row shape carries the park fields, and the README names the park label and the overridable bounds. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- plugins/agentic-engineering/CHANGELOG.md | 9 ++-- plugins/agentic-engineering/README.md | 7 ++- .../agents/agentic-engineer.agent.md | 4 +- .../agents/portfolio-surveyor.agent.md | 35 +++++++++----- .../provider-neutral.desired-state.json | 4 +- .../parked-pr-ownership-contract.test.sh | 18 ++++++-- .../skills/portfolio-maintenance/SKILL.md | 4 +- .../references/driving-prs.md | 46 ++++++++++++------- 8 files changed, 84 insertions(+), 43 deletions(-) diff --git a/plugins/agentic-engineering/CHANGELOG.md b/plugins/agentic-engineering/CHANGELOG.md index 8991494c..54413234 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -13,10 +13,13 @@ route. The agent takes engineering routes itself and keeps taking them, recordin tried, the next route, and when it will look again. Ownership stays with the agent. A park never hands work to the maintainer, and no bound makes contacting the maintainer the outcome. A maintainer-ask is only for a genuine question of direction, with the default the agent will act on, -and the work continues meanwhile. An update ecosystem whose open-PR limit is filled by parked PRs +and the work continues meanwhile. An update ecosystem at or near its open-PR limit with any PR parked is a stall, and a PR that does not depend on its named blocker is unparked and driven. The -**Cadence** can set another bound. The `portfolio-surveyor` reports `parked`, `blocker` and `decision` facts for each parked -candidate PR, and `unknown` when it cannot read them. `parked-pr-ownership-contract.test.sh` pins +**Cadence** can set another bound. Automation-owned PRs stay outside these rules. The +`portfolio-surveyor` reads each candidate's labels itself, from a complete per-PR list, and +reports `parked` (from the first park), `blocker` (including `decision` for a scope or design +blocker) and `decision` facts for each parked candidate PR, or `unknown` when it cannot read them. +A blocker it cannot read never justifies unparking. `parked-pr-ownership-contract.test.sh` pins the clauses. ## 7.6.8 — 2026-11-12 diff --git a/plugins/agentic-engineering/README.md b/plugins/agentic-engineering/README.md index 24ba1f21..e8503e18 100644 --- a/plugins/agentic-engineering/README.md +++ b/plugins/agentic-engineering/README.md @@ -438,14 +438,17 @@ The consuming repository's canonical `AGENTS.md` must define five named sections skills fail closed when any are absent: - **Portfolio map** — repositories in scope and each product's `## Maintenance` card, including - validate commands, labels, protected/generated files, roadmap home, and the standard + validate commands, labels (including the label that parks blocked work, which the surveyor reads + for park facts), protected/generated files, roadmap home, and the standard **feature-flag mechanism** required for non-trivial feature work. - **Trust gate** — trusted identities, reviewer-only identities, repository merge mechanics, and the **maintainer-PR driving** fact. `hands-off` (the default when it is absent) lets the engineer drive a PR under the maintainer's own login only when it created that PR and the maintainer has not taken it over interactively. `attribution-only` gives it every such PR under the deployment's own active-work rules, and uses the interactive-session marker only to tell whose comments are whose. -- **Cadence** — run frequency, run budget, and rotation intervals. +- **Cadence** — run frequency, run budget, and rotation intervals, plus any override of the + parked-PR bounds (re-check an upstream blocker at least every 7 days; take engineering routes on a + dependency PR parked past 14 days). - **Memory** — durable-store location, schema, and cross-run cursors. - **Maintainer channels** — active decision channels, the canonical AI-disclosure line, and the maintainer's interactive-session marker (the literal a PR body carries when it came from the diff --git a/plugins/agentic-engineering/agents/agentic-engineer.agent.md b/plugins/agentic-engineering/agents/agentic-engineer.agent.md index 70a87cdc..0559cfc5 100644 --- a/plugins/agentic-engineering/agents/agentic-engineer.agent.md +++ b/plugins/agentic-engineering/agents/agentic-engineer.agent.md @@ -144,8 +144,8 @@ merge path; a shared definition's portfolio-owned upstream remains on that portf blocked-work mechanism stays owned work. Work its blocker (an in-portfolio blocker is finishing work, ahead of new pulls; an upstream one is re-checked on a cadence, with an engineering route considered each time). Unblock a dependency PR parked past its bound by engineering routes you - take yourself, recording what you tried and the next route. Treat an update ecosystem whose - open-PR limit is filled by parked PRs as a stall, and unpark and drive a mis-park. Ownership stays + take yourself, recording what you tried and the next route. Treat an update ecosystem at or near + its open-PR limit with any PR parked as a stall, and unpark and drive a mis-park. Ownership stays with you: a park never hands work to the maintainer, and no timer makes contacting the maintainer the outcome. The `portfolio-maintenance` PR-driving procedure holds the complete rules. Every dependency update is read as a release range, regardless of diff --git a/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md b/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md index bf54bc05..ef8e4441 100644 --- a/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md +++ b/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md @@ -188,7 +188,8 @@ branch pattern as the classifier. For the remaining open PRs by the maintainer's login or an actionable trusted-bot author — **drafts and non-drafts** — pull the heavy fields with **per-PR semantics**: state, merge state, review decision, status-check rollup, review threads (for the review lanes — the unresolved count is step -3b's helper), head ref name, head ref oid, author, body, files. A +3b's helper), head ref name, head ref oid, author, body, files, and labels with their `totalCount` (the +only source for 3b's park facts). A transport request may carry at most eight independently keyed PRs under the mandatory-query recovery contract above; never pull a status-check rollup for every PR in every repo or make one generated query the fate of the whole worklist. @@ -312,13 +313,25 @@ included**, automation-owned dependency PRs excluded — report: - **(e) green-review state** — see below. **Park facts, for a parked PR.** A PR the consumer parked through its blocked-work mechanism is -still a candidate, never settled. When a candidate carries the consumer's blocked-work label, also -report `parked=<UTC date the label was last applied>`, `blocker=<owner/repo#n|upstream|none>` as the -consumer's blocked-work record on the PR names it, and `decision=<UTC date of the latest recorded -park decision>|none`. Read the date from the PR's own label events and the record from the PR -itself. A read that fails, or a record you cannot parse, reports that field as `unknown`, never a -guessed date or `none`. The orchestrator applies its PR-driving procedure's parked-PR rules to -these facts; never omit a parked PR from the digest, or classify it as finished, because it is parked. +still a candidate, never settled. Judge whether it is parked only from this PR's own per-PR label +list, whose returned names must match its `totalCount`, against the park label the consumer's +**Portfolio map** names; never from a census or search row, which can drop a label. A list cut +short, or a consumer that names no park label, reports `parked=unknown`. A parked candidate also +reports: + +- `parked=<UTC date the PR was first parked>`: the creation of the consumer's park record on the PR + or, without one, the earliest application of the park label. Read the label events across every + page; a later relabel never restarts the clock. +- `blocker=<owner/repo#n|upstream|decision|none>`: what the consumer's park record on the PR names. + `decision` is a scope or design decision, such as the re-entry condition of a review that did not + converge. +- `decision=<UTC date of the latest recorded route or decision on the park record>|none`. + +A read that fails, a page left unread, or a record you cannot parse reports that field as +`unknown`, never a guessed date or `none`. These reads are required evidence for a parked candidate +and count against the per-PR read budget like the pentad. The orchestrator applies its PR-driving +procedure's parked-PR rules to these facts. Never omit a parked PR from the digest, or classify it +as finished, because it is parked. A PR is review-ready only when current-head body findings **and** unresolved threads are 0, there is no ordinary failing check (a `managed-failing` check alone does not count), it is not @@ -925,9 +938,9 @@ budget: graphql=<start>→<end>/<limit> · core=<start>→<end>/<limit>[ · EXHA - REPO-SET-DRIFT — live set vs Portfolio map: new=<repos> · missing/renamed=<repos> · map-drift=<product rows missing/renamed live> → orchestrator reconciles (archived-marked rows exempt) - <repo>: CI red on <default-branch> @<sha> — <check name> <conclusion> (<run url>), event=<event>, path=<path>, created=<created_at>, run=<run_id>, attempt=<run_attempt> # judged at that branch's current head; routing fields come directly from the classifier; omit the repo when green - <repo> #<n> "<title>" — <exact bot identity> → AUTOMATION-OWNED (NO-ACTION) -- <repo> #<n> (trusted bot, draft) — pentad: checks=<green|failing:X|managed-failing:X|failing:X+managed-failing:Y>, unresolved=<n|unknown>, body_findings=<n>@<sha>|<n>-stale@<sha>|0-resolved@<sha>, green_review=<…>, review_reservation=<…>, review_pending=<…>, review_progress=<…>, rd=<APPROVED|CHANGES_REQUESTED:<author>@<sha>|none>, mergeState=<…>[, parked=<date|unknown>, blocker=<…|unknown>, decision=<date|none|unknown>] → REVIEW-READY | NEEDS-FIX | STALE-CR-DISMISSAL -- <repo> #<n> (trusted bot, non-draft) — pentad: <same fields> → MERGE-READY | NEEDS-FIX | STALE-CR-DISMISSAL -- <repo> #<n> "<title>" — maintainer login, draft=<true|false> → OWNERSHIP-UNVERIFIED: branch=<headRefName>, disclosure=<routine|interactive|none>, pentad=<…>, review_reservation=<…>, review_pending=<…>, review_progress=<…> → NEEDS-FIX | CLEAR (pentad disposition only — orchestrator applies creation-record test before action; never MERGE-READY, never asserted mine) +- <repo> #<n> (trusted bot, draft) — pentad: checks=<green|failing:X|managed-failing:X|failing:X+managed-failing:Y>, unresolved=<n|unknown>, body_findings=<n>@<sha>|<n>-stale@<sha>|0-resolved@<sha>, green_review=<…>, review_reservation=<…>, review_pending=<…>, review_progress=<…>, rd=<APPROVED|CHANGES_REQUESTED:<author>@<sha>|none>, mergeState=<…>[, parked=<date|unknown>, blocker=<owner/repo#n|upstream|decision|none|unknown>, decision=<date|none|unknown>] → REVIEW-READY | NEEDS-FIX | STALE-CR-DISMISSAL +- <repo> #<n> (trusted bot, non-draft) — pentad: <same fields> (park fields included) → MERGE-READY | NEEDS-FIX | STALE-CR-DISMISSAL +- <repo> #<n> "<title>" — maintainer login, draft=<true|false> → OWNERSHIP-UNVERIFIED: branch=<headRefName>, disclosure=<routine|interactive|none>, pentad=<…>, [parked=<…>, blocker=<…>, decision=<…>,] review_reservation=<…>, review_pending=<…>, review_progress=<…> → NEEDS-FIX | CLEAR (pentad disposition only — orchestrator applies creation-record test before action; never MERGE-READY, never asserted mine) - <repo>: untriaged → issues #a,#b · PRs #c | stale (>14d) → #d - <repo> #<n> "<title>" — <author>: EXTERNAL — review statically only (never auto-drive/merge) diff --git a/plugins/agentic-engineering/resources/provider-neutral.desired-state.json b/plugins/agentic-engineering/resources/provider-neutral.desired-state.json index 1d20ec51..211a3b09 100644 --- a/plugins/agentic-engineering/resources/provider-neutral.desired-state.json +++ b/plugins/agentic-engineering/resources/provider-neutral.desired-state.json @@ -42,7 +42,7 @@ "executable": true } ], - "entrypointSha256": "214c774907c50a1b491f1f05cbce34d6398240ed558e2291cb35d47ce858ed64", + "entrypointSha256": "fb1fb5ee883e0cabae88d3d4d2051265b76c587505bd363220170dd05b9609b1", "updatePolicy": "latest-reviewed-default-branch", "providerPolicy": "neutral", "refreshTiming": "before-starting-each-run", @@ -76,7 +76,7 @@ "portfolio-surveyor": { "enabled": true, "mode": "delegated-read-only", - "definitionSha256": "cb23eff17c5ff48c189aa208128455fd1d558868373d838f69c8d49285447a9c" + "definitionSha256": "9daa2763b86ef617a52c07778898d58c64e58249dd9a0b8130af8e7398aed724" }, "agent-improver": { "enabledWhen": "Both optional consumer contract sections are present", diff --git a/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh index 5978d353..5ce137bc 100755 --- a/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh +++ b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh @@ -25,7 +25,7 @@ agent_clauses=( "an upstream one is re-checked on a cadence, with an engineering route considered each time" "unblock a dependency pr parked past its bound by engineering routes you take yourself, recording what you tried and the next route." "ownership stays with you: a park never hands work to the maintainer, and no timer makes contacting the maintainer the outcome." - "treat an update ecosystem whose open-pr limit is filled by parked prs as a stall" + "treat an update ecosystem at or near its open-pr limit with any pr parked as a stall" "unpark and drive a mis-park." ) skill_clauses=( @@ -35,7 +35,9 @@ skill_clauses=( "work the in-portfolio blocker behind every parked pr" # The complete rule, in the PR-driving procedure the skill links. "a parked pr is not a resting place." - "the blocker a park names is owned work, and these rules apply to every parked pr on every run that drives prs:" + "the blocker a park names is owned work, and these rules apply to every parked pr on every run that drives prs." + "a pr the consumer's contract designates automation-owned stays outside them, exactly as the survey leaves it." + "never from the latest relabel, so a re-park keeps the earlier date and errs toward more work, never less." "an in-portfolio blocker is finishing work." "an unclaimed in-portfolio blocker behind a parked pr is a finding, never a wait." "make that decision yourself, and never resume fixing its findings one by one." @@ -46,7 +48,8 @@ skill_clauses=( "once it has been parked for 14 days, unless the cadence names another bound, waiting is no longer a route." "take an engineering route yourself, and keep taking them until the pr merges:" "record on the pr what you tried and what it showed, the next route you will take," - "a missing or lapsed record makes the pr actionable again." + "a missing or lapsed record makes taking the next route finishing work this run. it never lifts the park or the merge hold" + "an ignore is a lasting configuration change: record it on the blocker, and remove it when the blocker clears." # The maintainer owns direction, not the work (maintainer, 2026-11-13): no bound hands it over. "ownership stays with you." "no timer or bound makes contacting the maintainer the outcome." @@ -54,14 +57,19 @@ skill_clauses=( "such an ask is never a handoff and never a substitute for the work: state the default you will act on if no answer comes, and keep working the routes meanwhile." "an update ecosystem at or near its open-pr limit is stalled." "raising the limit alone hides the stall instead of clearing it." + "a blocker you cannot read, or a record that names none, never justifies unparking" "a mis-park is unparked and driven. at every check, confirm the pr really depends on its named blocker:" - "when its park facts (when it was parked, its blocker, its latest decision) cannot be read, the pr is unknown, never settled." + "when its park facts (when it was parked, its blocker, its latest route record) cannot be read, the pr is unknown, never settled." ) surveyor_clauses=( "a pr the consumer parked through its blocked-work mechanism is still a candidate, never settled." "reports that field as \`unknown\`, never a guessed date or \`none\`." "never omit a parked pr from the digest, or classify it as finished, because it is parked." "parked=<date|unknown>" + "never from a census or search row, which can drop a label." + "a later relabel never restarts the clock." + "\`blocker=<owner/repo#n|upstream|decision|none>\`" + "decision=<date|none|unknown>" ) # A sentence that would make any of the three read a park as settled, or hand it to the maintainer. forbidden_clauses=( @@ -69,6 +77,8 @@ forbidden_clauses=( "parked prs are finished" "raise it once through the deployment's maintainer channels" "past a longer bound" + # Dependabot security updates have their own open-PR limit, so a version-update stall never blocks them. + "security fixes included" ) normalize() { diff --git a/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md b/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md index 27d8a41a..311da297 100644 --- a/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md +++ b/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md @@ -143,8 +143,8 @@ draft is unfinished work to clear first. Keep every open own/trusted PR hygienic while it waits, dependency PRs included, and complete the upstream release review before promoting or merging a dependency update. A parked PR is not finished: its blocker is owned work, a dependency PR parked past its bound is unblocked by - engineering routes you take yourself, an update ecosystem whose open-PR limit is filled by parked - PRs is a stall, and a mis-park is unparked and driven. Ownership never moves to the maintainer. + engineering routes you take yourself, an update ecosystem at or near its open-PR limit with any PR + parked is a stall, and a mis-park is unparked and driven. Ownership never moves to the maintainer. Never run or auto-merge an external contributor's branch. **Read [the PR-driving procedure](references/driving-prs.md) before driving, promoting or merging any PR**; it is the complete rung. diff --git a/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md b/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md index da898770..df3424fd 100644 --- a/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md +++ b/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md @@ -56,28 +56,36 @@ keeps only its summary. **A parked PR is not a resting place.** Parking a PR through the deployment's blocked-work mechanism records why it cannot merge yet. It never settles the PR: a run that counts parked PRs as finished lets them strand for weeks while nobody works what holds them. The blocker a park - names is owned work, and these rules apply to every parked PR on every run that drives PRs: + names is owned work, and these rules apply to every parked PR on every run that drives PRs. A PR + the consumer's contract designates automation-owned stays outside them, exactly as the survey + leaves it. A park's age runs from when the PR was first parked (its park record's creation, or + the first time the park label was applied), never from the latest relabel, so a re-park keeps + the earlier date and errs toward more work, never less. - **An in-portfolio blocker is finishing work.** When the blocker is an issue, PR or decision inside the Portfolio map, rank it with your in-flight PRs, ahead of any new pull: claim it - through the deployment's claim mechanism and work it to its own terminal state. An unclaimed - in-portfolio blocker behind a parked PR is a finding, never a wait. For a PR parked on a review - that did not converge, the blocker is the scope or design decision its record names: make that - decision yourself, and never resume fixing its findings one by one. + through the deployment's claim mechanism (its **Writer namespaces** or claim protocol) and work + it to its own terminal state. An unclaimed in-portfolio blocker behind a parked PR is a finding, + never a wait. For a PR parked on a review that did not converge, the blocker is the scope or + design decision its record names: make that decision yourself, and never resume fixing its + findings one by one. - **An upstream blocker is re-checked, not waited on.** Re-verify it against live upstream state (releases, tags, and the upstream issue or PR) at least every 7 days unless the **Cadence** names another interval, and on every re-check date the park records. Each check also weighs an engineering route instead of only waiting: adapt the product to the new version; fork or patch the dependency; isolate or replace the conflicting dependency; contribute the fix upstream - under the egress and upstream-contribution rules; or split or ignore only the blocked part of a - grouped update, so the rest merges now. A route taken is ordinary work under the normal - readiness gates. + under the egress rules and [the upstream contribution procedure](upstream-contributions.md); or + split or ignore only the blocked part of a grouped update, so the rest merges now. An ignore is + a lasting configuration change: record it on the blocker, and remove it when the blocker clears. + A route taken is ordinary work under the normal readiness gates. - **Past its bound, a parked dependency-update PR is yours to unblock by engineering.** Once it has been parked for 14 days, unless the **Cadence** names another bound, waiting is no longer a route. Take an engineering route yourself, and keep taking them until the PR merges: adapt the product, fork or patch the dependency, isolate or replace the conflicting dependency, contribute upstream, or split the update so the unblocked part merges. Record on the PR what you tried and what it showed, the next route you will take, and the date you will look again, - at most one bound ahead. A missing or lapsed record makes the PR actionable again. + at most one bound ahead. A missing or lapsed record makes taking the next route finishing work + this run. It never lifts the park or the merge hold: the PR merges only once its blocker clears + and genuine readiness holds. - **Ownership stays with you.** You own the code and its dependency updates, never the maintainer. A park never hands work to the maintainer, and no timer or bound makes contacting the maintainer the outcome. Use the deployment's **Maintainer channels** only for a genuine @@ -86,15 +94,19 @@ keeps only its summary. you will act on if no answer comes, and keep working the routes meanwhile. - **An update ecosystem at or near its open-PR limit is stalled.** When the open PRs of one dependency-update configuration (one package manager and directory) reach its configured - open-PR limit, or are one short of it, and any of them is parked, new updates stop opening, - security fixes included. Treat that as finishing work: unblock, combine or narrow the parked - updates (for example, ignore only the blocked version range and record that on the blocker) so - slots free up. Raising the limit alone hides the stall instead of clearing it. + open-PR limit, or are one short of it, and any of them is parked, new updates stop opening. For + a tool whose security updates share that limit, security fixes stop too; Dependabot's security + updates have their own limit. Treat the stall as finishing work: unblock, combine or narrow the + parked updates (for example, ignore only the blocked version range, recorded on the blocker and + removed when it clears) so slots free up. Raising the limit alone hides the stall instead of + clearing it. - **A mis-park is unparked and driven.** At every check, confirm the PR really depends on its named blocker: the change touches what the blocker names, and the blocker is still open and - still holds. A PR that does not depend on it (the wrong blocker, a blocker already closed or - resolved, or one that holds only another part of a grouped update) is unparked through the - same mechanism and driven like any other PR. + still holds. A PR that verifiably does not depend on it (the wrong blocker, a blocker already + closed or resolved, or one that holds only another part of a grouped update) is unparked + through the same mechanism and driven like any other PR. A scope or design decision is a + blocker too. A blocker you cannot read, or a record that names none, never justifies + unparking: repair or re-verify the record instead. A parked PR never leaves the survey. When its park facts (when it was parked, its blocker, its - latest decision) cannot be read, the PR is unknown, never settled. + latest route record) cannot be read, the PR is unknown, never settled. From 1efa3bbd2f594a1d3ccac023d37d7b4108143a99 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm <nikolaiemildamm@icloud.com> Date: Fri, 13 Nov 2026 01:43:02 +0100 Subject: [PATCH 4/5] refactor(agentic-engineering): reshape the parked-PR rule around behaviour, not survey mechanics Review round 2 on #699 returned findings of the kind round 1 already raised (park-date sourcing, label reads, ignore tracking): the surveyor was specifying park-fact mechanics that belong to each deployment's own park mechanism. Reshape once, per agent rule 3: - the surveyor and the survey procedure keep only the behaviour: a parked PR stays in the survey with its pentad and is never reported as finished; the deployment supplies park facts; - the PR-driving rule adds what the behaviour needs: a parked PR is never merged while parked; routes live in the one park record, edited in place; a blocker clears only when its fix is verifiably available to the product (closed-unfixed or not-planned still holds); an ignore is tracked on an in-portfolio issue until removed, never by writing upstream; the stall rule reads each entry's effective limit; routes continue until the PR merges or closes for a recorded reason. The contract test follows both linked references and pins the new clauses. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- plugins/agentic-engineering/CHANGELOG.md | 11 +-- plugins/agentic-engineering/README.md | 3 +- .../agents/portfolio-surveyor.agent.md | 34 +++------ .../provider-neutral.desired-state.json | 2 +- .../parked-pr-ownership-contract.test.sh | 74 +++++++++++-------- .../skills/portfolio-maintenance/SKILL.md | 3 +- .../references/driving-prs.md | 56 +++++++------- .../references/survey.md | 2 +- 8 files changed, 93 insertions(+), 92 deletions(-) diff --git a/plugins/agentic-engineering/CHANGELOG.md b/plugins/agentic-engineering/CHANGELOG.md index 54413234..04d1bd95 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -15,11 +15,12 @@ hands work to the maintainer, and no bound makes contacting the maintainer the o maintainer-ask is only for a genuine question of direction, with the default the agent will act on, and the work continues meanwhile. An update ecosystem at or near its open-PR limit with any PR parked is a stall, and a PR that does not depend on its named blocker is unparked and driven. The -**Cadence** can set another bound. Automation-owned PRs stay outside these rules. The -`portfolio-surveyor` reads each candidate's labels itself, from a complete per-PR list, and -reports `parked` (from the first park), `blocker` (including `decision` for a scope or design -blocker) and `decision` facts for each parked candidate PR, or `unknown` when it cannot read them. -A blocker it cannot read never justifies unparking. `parked-pr-ownership-contract.test.sh` pins +**Cadence** can set another bound. Automation-owned PRs stay outside these rules. A parked PR is +never merged while parked; a blocker clears only when its fix is verifiably available to the +product, and one that cannot be read never justifies unparking. An ignore is tracked on an +in-portfolio issue until it is removed. The `portfolio-surveyor` and the survey procedure keep +every parked PR in the survey and never report it as finished; the deployment's own park +mechanism supplies its park facts. `parked-pr-ownership-contract.test.sh` pins the clauses. ## 7.6.8 — 2026-11-12 diff --git a/plugins/agentic-engineering/README.md b/plugins/agentic-engineering/README.md index e8503e18..4816313d 100644 --- a/plugins/agentic-engineering/README.md +++ b/plugins/agentic-engineering/README.md @@ -438,8 +438,7 @@ The consuming repository's canonical `AGENTS.md` must define five named sections skills fail closed when any are absent: - **Portfolio map** — repositories in scope and each product's `## Maintenance` card, including - validate commands, labels (including the label that parks blocked work, which the surveyor reads - for park facts), protected/generated files, roadmap home, and the standard + validate commands, labels, protected/generated files, roadmap home, and the standard **feature-flag mechanism** required for non-trivial feature work. - **Trust gate** — trusted identities, reviewer-only identities, repository merge mechanics, and the **maintainer-PR driving** fact. `hands-off` (the default when it is absent) lets the engineer drive diff --git a/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md b/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md index ef8e4441..f6bb815d 100644 --- a/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md +++ b/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md @@ -188,8 +188,7 @@ branch pattern as the classifier. For the remaining open PRs by the maintainer's login or an actionable trusted-bot author — **drafts and non-drafts** — pull the heavy fields with **per-PR semantics**: state, merge state, review decision, status-check rollup, review threads (for the review lanes — the unresolved count is step -3b's helper), head ref name, head ref oid, author, body, files, and labels with their `totalCount` (the -only source for 3b's park facts). A +3b's helper), head ref name, head ref oid, author, body, files. A transport request may carry at most eight independently keyed PRs under the mandatory-query recovery contract above; never pull a status-check rollup for every PR in every repo or make one generated query the fate of the whole worklist. @@ -312,26 +311,11 @@ included**, automation-owned dependency PRs excluded — report: - **(d) merge conflicts / behind-base state.** - **(e) green-review state** — see below. -**Park facts, for a parked PR.** A PR the consumer parked through its blocked-work mechanism is -still a candidate, never settled. Judge whether it is parked only from this PR's own per-PR label -list, whose returned names must match its `totalCount`, against the park label the consumer's -**Portfolio map** names; never from a census or search row, which can drop a label. A list cut -short, or a consumer that names no park label, reports `parked=unknown`. A parked candidate also -reports: - -- `parked=<UTC date the PR was first parked>`: the creation of the consumer's park record on the PR - or, without one, the earliest application of the park label. Read the label events across every - page; a later relabel never restarts the clock. -- `blocker=<owner/repo#n|upstream|decision|none>`: what the consumer's park record on the PR names. - `decision` is a scope or design decision, such as the re-entry condition of a review that did not - converge. -- `decision=<UTC date of the latest recorded route or decision on the park record>|none`. - -A read that fails, a page left unread, or a record you cannot parse reports that field as -`unknown`, never a guessed date or `none`. These reads are required evidence for a parked candidate -and count against the per-PR read budget like the pentad. The orchestrator applies its PR-driving -procedure's parked-PR rules to these facts. Never omit a parked PR from the digest, or classify it -as finished, because it is parked. +**A parked PR is still a candidate.** A PR the consumer parked through its blocked-work mechanism +stays in this section and in the digest with its pentad, like any other PR. Never omit it, or +report it as finished, because it is parked. The consumer's own park mechanism supplies its park +facts, and the orchestrator's PR-driving procedure decides what they require, including that a +parked PR is never merged while it is parked. A PR is review-ready only when current-head body findings **and** unresolved threads are 0, there is no ordinary failing check (a `managed-failing` check alone does not count), it is not @@ -938,9 +922,9 @@ budget: graphql=<start>→<end>/<limit> · core=<start>→<end>/<limit>[ · EXHA - REPO-SET-DRIFT — live set vs Portfolio map: new=<repos> · missing/renamed=<repos> · map-drift=<product rows missing/renamed live> → orchestrator reconciles (archived-marked rows exempt) - <repo>: CI red on <default-branch> @<sha> — <check name> <conclusion> (<run url>), event=<event>, path=<path>, created=<created_at>, run=<run_id>, attempt=<run_attempt> # judged at that branch's current head; routing fields come directly from the classifier; omit the repo when green - <repo> #<n> "<title>" — <exact bot identity> → AUTOMATION-OWNED (NO-ACTION) -- <repo> #<n> (trusted bot, draft) — pentad: checks=<green|failing:X|managed-failing:X|failing:X+managed-failing:Y>, unresolved=<n|unknown>, body_findings=<n>@<sha>|<n>-stale@<sha>|0-resolved@<sha>, green_review=<…>, review_reservation=<…>, review_pending=<…>, review_progress=<…>, rd=<APPROVED|CHANGES_REQUESTED:<author>@<sha>|none>, mergeState=<…>[, parked=<date|unknown>, blocker=<owner/repo#n|upstream|decision|none|unknown>, decision=<date|none|unknown>] → REVIEW-READY | NEEDS-FIX | STALE-CR-DISMISSAL -- <repo> #<n> (trusted bot, non-draft) — pentad: <same fields> (park fields included) → MERGE-READY | NEEDS-FIX | STALE-CR-DISMISSAL -- <repo> #<n> "<title>" — maintainer login, draft=<true|false> → OWNERSHIP-UNVERIFIED: branch=<headRefName>, disclosure=<routine|interactive|none>, pentad=<…>, [parked=<…>, blocker=<…>, decision=<…>,] review_reservation=<…>, review_pending=<…>, review_progress=<…> → NEEDS-FIX | CLEAR (pentad disposition only — orchestrator applies creation-record test before action; never MERGE-READY, never asserted mine) +- <repo> #<n> (trusted bot, draft) — pentad: checks=<green|failing:X|managed-failing:X|failing:X+managed-failing:Y>, unresolved=<n|unknown>, body_findings=<n>@<sha>|<n>-stale@<sha>|0-resolved@<sha>, green_review=<…>, review_reservation=<…>, review_pending=<…>, review_progress=<…>, rd=<APPROVED|CHANGES_REQUESTED:<author>@<sha>|none>, mergeState=<…> → REVIEW-READY | NEEDS-FIX | STALE-CR-DISMISSAL +- <repo> #<n> (trusted bot, non-draft) — pentad: <same fields> → MERGE-READY | NEEDS-FIX | STALE-CR-DISMISSAL +- <repo> #<n> "<title>" — maintainer login, draft=<true|false> → OWNERSHIP-UNVERIFIED: branch=<headRefName>, disclosure=<routine|interactive|none>, pentad=<…>, review_reservation=<…>, review_pending=<…>, review_progress=<…> → NEEDS-FIX | CLEAR (pentad disposition only — orchestrator applies creation-record test before action; never MERGE-READY, never asserted mine) - <repo>: untriaged → issues #a,#b · PRs #c | stale (>14d) → #d - <repo> #<n> "<title>" — <author>: EXTERNAL — review statically only (never auto-drive/merge) diff --git a/plugins/agentic-engineering/resources/provider-neutral.desired-state.json b/plugins/agentic-engineering/resources/provider-neutral.desired-state.json index 211a3b09..8e7a72de 100644 --- a/plugins/agentic-engineering/resources/provider-neutral.desired-state.json +++ b/plugins/agentic-engineering/resources/provider-neutral.desired-state.json @@ -76,7 +76,7 @@ "portfolio-surveyor": { "enabled": true, "mode": "delegated-read-only", - "definitionSha256": "9daa2763b86ef617a52c07778898d58c64e58249dd9a0b8130af8e7398aed724" + "definitionSha256": "24aaef936a52b0bc5bd646ff13f0c044394d9fe336d194efee5fdc30683990c4" }, "agent-improver": { "enabledWhen": "Both optional consumer contract sections are present", diff --git a/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh index 5ce137bc..b4ef4082 100755 --- a/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh +++ b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh @@ -32,12 +32,16 @@ skill_clauses=( # The run loop's own summary, so a run that never opens the reference still meets the rule. "a parked pr is not finished: its blocker is owned work" "ownership never moves to the maintainer." - "work the in-portfolio blocker behind every parked pr" + "work the in-portfolio blocker behind every parked pr (automation-owned prs aside)" + # The survey procedure the skill links, which an inline survey follows. + "parked or not: a parked pr stays in the survey and is never reported as finished" # The complete rule, in the PR-driving procedure the skill links. "a parked pr is not a resting place." "the blocker a park names is owned work, and these rules apply to every parked pr on every run that drives prs." "a pr the consumer's contract designates automation-owned stays outside them, exactly as the survey leaves it." + "a parked pr is never merged while it is parked: once its blocker verifiably clears, lift the park through the same mechanism, then drive the pr to merge under the normal gates." "never from the latest relabel, so a re-park keeps the earlier date and errs toward more work, never less." + "keep every route, decision and re-check date in that one record, edited in place." "an in-portfolio blocker is finishing work." "an unclaimed in-portfolio blocker behind a parked pr is a finding, never a wait." "make that decision yourself, and never resume fixing its findings one by one." @@ -45,31 +49,29 @@ skill_clauses=( "at least every 7 days unless the cadence names another interval" "each check also weighs an engineering route instead of only waiting:" "or split or ignore only the blocked part of a grouped update, so the rest merges now." + "track it on an in-portfolio issue that stays open until the ignore is removed (never by writing on an upstream artifact)" "once it has been parked for 14 days, unless the cadence names another bound, waiting is no longer a route." - "take an engineering route yourself, and keep taking them until the pr merges:" - "record on the pr what you tried and what it showed, the next route you will take," - "a missing or lapsed record makes taking the next route finishing work this run. it never lifts the park or the merge hold" - "an ignore is a lasting configuration change: record it on the blocker, and remove it when the blocker clears." + "take an engineering route yourself, and keep taking them until the pr merges or is closed for a recorded reason:" + "record in the park record what you tried and what it showed, the next route you will take," + "a missing or lapsed record makes taking the next route finishing work this run. it never lifts the park or the merge hold." # The maintainer owns direction, not the work (maintainer, 2026-11-13): no bound hands it over. "ownership stays with you." "no timer or bound makes contacting the maintainer the outcome." "only for a genuine question of direction you cannot settle on your own, and never to ask about what you can do yourself." "such an ask is never a handoff and never a substitute for the work: state the default you will act on if no answer comes, and keep working the routes meanwhile." "an update ecosystem at or near its open-pr limit is stalled." + "the configured value, or the tool's default when it sets none." "raising the limit alone hides the stall instead of clearing it." + "a blocker has cleared only when its fix is verifiably available to the product:" + "an upstream item closed without a released fix, or closed as not planned, still holds." "a blocker you cannot read, or a record that names none, never justifies unparking" "a mis-park is unparked and driven. at every check, confirm the pr really depends on its named blocker:" - "when its park facts (when it was parked, its blocker, its latest route record) cannot be read, the pr is unknown, never settled." + "cannot be read, the pr is unknown: never settled, and never merged." ) surveyor_clauses=( - "a pr the consumer parked through its blocked-work mechanism is still a candidate, never settled." - "reports that field as \`unknown\`, never a guessed date or \`none\`." - "never omit a parked pr from the digest, or classify it as finished, because it is parked." - "parked=<date|unknown>" - "never from a census or search row, which can drop a label." - "a later relabel never restarts the clock." - "\`blocker=<owner/repo#n|upstream|decision|none>\`" - "decision=<date|none|unknown>" + "a pr the consumer parked through its blocked-work mechanism stays in this section and in the digest with its pentad, like any other pr." + "never omit it, or report it as finished, because it is parked." + "including that a parked pr is never merged while it is parked." ) # A sentence that would make any of the three read a park as settled, or hand it to the maintainer. forbidden_clauses=( @@ -108,31 +110,39 @@ check() { done } -# The skill keeps a summary and links the complete rung in references/driving-prs.md. Check the text -# an agent reads by following that link: the skill with the reference inserted after the first line -# that links it. A dropped link or an emptied reference removes the clauses, so the check fails closed. -linked_skill() { # skill-dir output reference - LC_ALL=C awk -v dir="$1" -v ref="$3" ' +# The skill keeps summaries and links the complete rung in references/driving-prs.md and the survey +# in references/survey.md. Check the text an agent reads by following those links: the skill with +# each reference inserted after the first line that links it. A dropped link or an emptied reference +# removes the clauses, so the check fails closed. +linked_skill() { # skill-dir output reference... + local dir="$1" out="$2" + shift 2 + LC_ALL=C awk -v dir="$dir" -v refs="$*" ' + BEGIN { n = split(refs, ref, " ") } { print - if (!done && index($0, "](" ref ")")) { - while ((getline line < (dir "/" ref)) > 0) print line - close(dir "/" ref) - done = 1 + for (i = 1; i <= n; i++) { + if (!done[i] && index($0, "](" ref[i] ")")) { + while ((getline line < (dir "/" ref[i])) > 0) print line + close(dir "/" ref[i]) + done[i] = 1 + } } } - ' "$1/SKILL.md" >"$2" + ' "$dir/SKILL.md" >"$out" } fail=0 -for f in "$agent" "$surveyor" "$skill_dir/SKILL.md" "$skill_dir/references/driving-prs.md"; do +for f in "$agent" "$surveyor" "$skill_dir/SKILL.md" "$skill_dir/references/driving-prs.md" "$skill_dir/references/survey.md"; do [ -r "$f" ] || { echo "cannot read $f" >&2; exit 1; } done -linked_skill "$skill_dir" "$tmp/linked-skill.md" references/driving-prs.md -grep -qF "A parked PR is not a resting place." "$tmp/linked-skill.md" || { - echo " ✗ SKILL.md no longer links references/driving-prs.md, so the linked text lacks the rule" >&2 - exit 1 -} +linked_skill "$skill_dir" "$tmp/linked-skill.md" references/driving-prs.md references/survey.md +for marker in "A parked PR is not a resting place." "parked or not: a parked PR stays in the survey"; do + grep -qF "$marker" "$tmp/linked-skill.md" || { + echo " ✗ SKILL.md no longer links the reference that holds: $marker" >&2 + exit 1 + } +done # surface <label> <file> <clause>... surface() { @@ -149,7 +159,7 @@ surface() { # from the normalised text, not the file. normalize "$file" >"$tmp/normalized.md" for clause in "${clauses[@]}"; do - awk -v clause="$clause" '{ + LC_ALL=C awk -v clause="$clause" '{ position = index($0, clause) if (position > 0) $0 = substr($0, 1, position - 1) substr($0, position + length(clause)) print @@ -178,7 +188,7 @@ surface() { } surface "agentic-engineer" "$agent" "${agent_clauses[@]}" -surface "portfolio-maintenance (with driving-prs.md)" "$tmp/linked-skill.md" "${skill_clauses[@]}" +surface "portfolio-maintenance (with its linked references)" "$tmp/linked-skill.md" "${skill_clauses[@]}" surface "portfolio-surveyor" "$surveyor" "${surveyor_clauses[@]}" completed=1 diff --git a/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md b/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md index 311da297..7728265d 100644 --- a/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md +++ b/plugins/agentic-engineering/skills/portfolio-maintenance/SKILL.md @@ -130,7 +130,8 @@ actionable work remains, **within the per-run budget and stop conditions the dep section sets** — an unattended run ends when actionable work is exhausted or blocked, or when that budget is spent, never merely after a few items. **Stop starting, start finishing:** before opening any new draft, drive every own in-flight PR to merged (self-promote when genuine readiness holds) or keep it draft with -the missing readiness condition named, and work the in-portfolio blocker behind every parked PR — a readiness-proven merge is the deliverable; a half-finished +the missing readiness condition named, and work the in-portfolio blocker behind every parked PR +(automation-owned PRs aside) — a readiness-proven merge is the deliverable; a half-finished draft is unfinished work to clear first. **Operate (keep it healthy) — always before advancing:** diff --git a/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md b/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md index df3424fd..feb35111 100644 --- a/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md +++ b/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md @@ -58,9 +58,12 @@ keeps only its summary. as finished lets them strand for weeks while nobody works what holds them. The blocker a park names is owned work, and these rules apply to every parked PR on every run that drives PRs. A PR the consumer's contract designates automation-owned stays outside them, exactly as the survey - leaves it. A park's age runs from when the PR was first parked (its park record's creation, or - the first time the park label was applied), never from the latest relabel, so a re-park keeps - the earlier date and errs toward more work, never less. + leaves it. A parked PR is never merged while it is parked: once its blocker verifiably clears, + lift the park through the same mechanism, then drive the PR to merge under the normal gates. A + park's age runs from when the PR was first parked, never from the latest relabel, so a re-park + keeps the earlier date and errs toward more work, never less. The deployment's park mechanism + supplies that date and the park record; keep every route, decision and re-check date in that one + record, edited in place. - **An in-portfolio blocker is finishing work.** When the blocker is an issue, PR or decision inside the Portfolio map, rank it with your in-flight PRs, ahead of any new pull: claim it through the deployment's claim mechanism (its **Writer namespaces** or claim protocol) and work @@ -75,38 +78,41 @@ keeps only its summary. the dependency; isolate or replace the conflicting dependency; contribute the fix upstream under the egress rules and [the upstream contribution procedure](upstream-contributions.md); or split or ignore only the blocked part of a grouped update, so the rest merges now. An ignore is - a lasting configuration change: record it on the blocker, and remove it when the blocker clears. - A route taken is ordinary work under the normal readiness gates. + a lasting configuration change: track it on an in-portfolio issue that stays open until the + ignore is removed (never by writing on an upstream artifact), re-check it on the same cadence, + and remove the ignore when the blocker clears. A route taken is ordinary work under the normal + readiness gates. - **Past its bound, a parked dependency-update PR is yours to unblock by engineering.** Once it has been parked for 14 days, unless the **Cadence** names another bound, waiting is no longer a - route. Take an engineering route yourself, and keep taking them until the PR merges: adapt the - product, fork or patch the dependency, isolate or replace the conflicting dependency, - contribute upstream, or split the update so the unblocked part merges. Record on the PR what - you tried and what it showed, the next route you will take, and the date you will look again, - at most one bound ahead. A missing or lapsed record makes taking the next route finishing work - this run. It never lifts the park or the merge hold: the PR merges only once its blocker clears - and genuine readiness holds. + route. Take an engineering route yourself, and keep taking them until the PR merges or is closed + for a recorded reason: adapt the product, fork or patch the dependency, isolate or replace the + conflicting dependency, contribute upstream, or split the update so the unblocked part merges. + Record in the park record what you tried and what it showed, the next route you will take, and + the date you will look again, at most one bound ahead. A missing or lapsed record makes taking + the next route finishing work this run. It never lifts the park or the merge hold. - **Ownership stays with you.** You own the code and its dependency updates, never the maintainer. A park never hands work to the maintainer, and no timer or bound makes contacting the maintainer the outcome. Use the deployment's **Maintainer channels** only for a genuine question of direction you cannot settle on your own, and never to ask about what you can do yourself. Such an ask is never a handoff and never a substitute for the work: state the default you will act on if no answer comes, and keep working the routes meanwhile. - - **An update ecosystem at or near its open-PR limit is stalled.** When the open PRs of one - dependency-update configuration (one package manager and directory) reach its configured - open-PR limit, or are one short of it, and any of them is parked, new updates stop opening. For - a tool whose security updates share that limit, security fixes stop too; Dependabot's security + - **An update ecosystem at or near its open-PR limit is stalled.** Read the effective open-PR + limit of each update configuration entry: the configured value, or the tool's default when it + sets none. When that entry's open PRs reach the limit, or come within one of it, and any of them + is parked, new version updates stop opening or are one update away from stopping. For a tool + whose security updates share that limit, security fixes stop too; Dependabot's security updates have their own limit. Treat the stall as finishing work: unblock, combine or narrow the - parked updates (for example, ignore only the blocked version range, recorded on the blocker and - removed when it clears) so slots free up. Raising the limit alone hides the stall instead of - clearing it. + parked updates (for example, ignore only the blocked version range, tracked as above) so slots + free up. Raising the limit alone hides the stall instead of clearing it. - **A mis-park is unparked and driven.** At every check, confirm the PR really depends on its - named blocker: the change touches what the blocker names, and the blocker is still open and - still holds. A PR that verifiably does not depend on it (the wrong blocker, a blocker already - closed or resolved, or one that holds only another part of a grouped update) is unparked - through the same mechanism and driven like any other PR. A scope or design decision is a - blocker too. A blocker you cannot read, or a record that names none, never justifies + named blocker: the change touches what the blocker names, and the blocker still holds. A blocker + has cleared 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. A PR that verifiably does not depend on its blocker (the + wrong blocker, a cleared one, or one that holds only another part of a grouped update) is + unparked through the same mechanism and driven like any other PR. A scope or design decision + is a blocker too. A blocker you cannot read, or a record that names none, never justifies unparking: repair or re-verify the record instead. A parked PR never leaves the survey. When its park facts (when it was parked, its blocker, its - latest route record) cannot be read, the PR is unknown, never settled. + latest route record) cannot be read, the PR is unknown: never settled, and never merged. diff --git a/plugins/agentic-engineering/skills/portfolio-maintenance/references/survey.md b/plugins/agentic-engineering/skills/portfolio-maintenance/references/survey.md index 011b2cfb..30e2982f 100644 --- a/plugins/agentic-engineering/skills/portfolio-maintenance/references/survey.md +++ b/plugins/agentic-engineering/skills/portfolio-maintenance/references/survey.md @@ -119,7 +119,7 @@ repositories must never enter the digest or selection set), deepening only the c a heavy per-repo loop. The survey covers, for every in-scope repository: - **Breakage:** CI red on the default branch; a broken build, site, or release pipeline. -- **Every open own/trusted-author PR** (drafts *and* promoted, fresh *and* old, merge-gated or not) +- **Every open own/trusted-author PR** (drafts *and* promoted, fresh *and* old, merge-gated or not, parked or not: a parked PR stays in the survey and is never reported as finished) with its full **hygiene pentad**: (a) failing checks; (b) unresolved review threads **plus any reviewer findings published outside threads** (some automated reviewers emit findings in review *bodies* or summary comments that never become resolvable threads — sweep every surface the From 6e3d547fd24cc30d41bd844a60c97f53638bd92c Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm <nikolaiemildamm@icloud.com> Date: Fri, 13 Nov 2026 02:12:24 +0100 Subject: [PATCH 5/5] fix(agentic-engineering): hold a parked PR's merge and bound how a park ends From the first review round after the recorded reshape on #699: - the pre-merge recheck now reads "not parked", parking disarms auto-merge and leaves any merge queue, and the surveyor says its MERGE-READY covers the pentad only; - a scope or design decision clears once it is recorded and its change is on the PR or merged; - a parked PR closes only when a newer update supersedes it or as a deliberate rejection, never to free a slot or clear the bound, and a close the tool records as an ignore is tracked as one; - the rules cover only PRs the Trust gate lets you drive, an unreadable age counts as past the bound, the look-again date never trails the upstream re-check, and a fork goes through the deployment's repository-creation path; - the contract test forbids broader handoff phrasings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- plugins/agentic-engineering/CHANGELOG.md | 7 ++- .../agents/portfolio-surveyor.agent.md | 7 +-- .../provider-neutral.desired-state.json | 2 +- .../parked-pr-ownership-contract.test.sh | 17 +++++-- .../references/driving-prs.md | 51 +++++++++++-------- 5 files changed, 54 insertions(+), 30 deletions(-) diff --git a/plugins/agentic-engineering/CHANGELOG.md b/plugins/agentic-engineering/CHANGELOG.md index 04d1bd95..8ccd2b78 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -16,8 +16,11 @@ maintainer-ask is only for a genuine question of direction, with the default the and the work continues meanwhile. An update ecosystem at or near its open-PR limit with any PR parked is a stall, and a PR that does not depend on its named blocker is unparked and driven. The **Cadence** can set another bound. Automation-owned PRs stay outside these rules. A parked PR is -never merged while parked; a blocker clears only when its fix is verifiably available to the -product, and one that cannot be read never justifies unparking. An ignore is tracked on an +never merged while parked: the pre-merge recheck reads it, and parking disarms auto-merge and +leaves any merge queue. A blocker clears only when its fix is verifiably available to the product +(a scope or design decision once it is recorded and its change is in place), and one that cannot +be read never justifies unparking. A parked PR closes only when a newer update supersedes it or as +a deliberate rejection, never to free a slot. An ignore is tracked on an in-portfolio issue until it is removed. The `portfolio-surveyor` and the survey procedure keep every parked PR in the survey and never report it as finished; the deployment's own park mechanism supplies its park facts. `parked-pr-ownership-contract.test.sh` pins diff --git a/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md b/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md index f6bb815d..ca7dcab4 100644 --- a/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md +++ b/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md @@ -313,9 +313,10 @@ included**, automation-owned dependency PRs excluded — report: **A parked PR is still a candidate.** A PR the consumer parked through its blocked-work mechanism stays in this section and in the digest with its pentad, like any other PR. Never omit it, or -report it as finished, because it is parked. The consumer's own park mechanism supplies its park -facts, and the orchestrator's PR-driving procedure decides what they require, including that a -parked PR is never merged while it is parked. +report it as finished, because it is parked. Its classification, `MERGE-READY` included, covers +the pentad only. The consumer's own park mechanism supplies its park facts, and the orchestrator's +PR-driving procedure decides what they require, including that a parked PR is never merged while +it is parked. A PR is review-ready only when current-head body findings **and** unresolved threads are 0, there is no ordinary failing check (a `managed-failing` check alone does not count), it is not diff --git a/plugins/agentic-engineering/resources/provider-neutral.desired-state.json b/plugins/agentic-engineering/resources/provider-neutral.desired-state.json index 8e7a72de..d29ed5b9 100644 --- a/plugins/agentic-engineering/resources/provider-neutral.desired-state.json +++ b/plugins/agentic-engineering/resources/provider-neutral.desired-state.json @@ -76,7 +76,7 @@ "portfolio-surveyor": { "enabled": true, "mode": "delegated-read-only", - "definitionSha256": "24aaef936a52b0bc5bd646ff13f0c044394d9fe336d194efee5fdc30683990c4" + "definitionSha256": "e3cf20337a2a1e3d1378e40e880a19cf279fcbd7cd419134d26b9e0f3f573c33" }, "agent-improver": { "enabledWhen": "Both optional consumer contract sections are present", diff --git a/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh index b4ef4082..5cd896b9 100755 --- a/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh +++ b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh @@ -39,7 +39,10 @@ skill_clauses=( "a parked pr is not a resting place." "the blocker a park names is owned work, and these rules apply to every parked pr on every run that drives prs." "a pr the consumer's contract designates automation-owned stays outside them, exactly as the survey leaves it." - "a parked pr is never merged while it is parked: once its blocker verifiably clears, lift the park through the same mechanism, then drive the pr to merge under the normal gates." + "a parked pr is never merged while it is parked." + "when you park a pr, disarm its auto-merge and take it out of any merge queue, so the park holds the merge." + "genuine readiness here includes that the pr is not parked." + "they cover only the prs the trust gate lets you drive." "never from the latest relabel, so a re-park keeps the earlier date and errs toward more work, never less." "keep every route, decision and re-check date in that one record, edited in place." "an in-portfolio blocker is finishing work." @@ -51,7 +54,9 @@ skill_clauses=( "or split or ignore only the blocked part of a grouped update, so the rest merges now." "track it on an in-portfolio issue that stays open until the ignore is removed (never by writing on an upstream artifact)" "once it has been parked for 14 days, unless the cadence names another bound, waiting is no longer a route." - "take an engineering route yourself, and keep taking them until the pr merges or is closed for a recorded reason:" + "take an engineering route yourself, and keep taking them until the pr merges or a newer update supersedes it:" + "closing it otherwise is the separate, deliberate decision to reject the update, never a way to free a slot or clear the bound." + "a close the update tool records as an ignore is an ignore, and is tracked as one." "record in the park record what you tried and what it showed, the next route you will take," "a missing or lapsed record makes taking the next route finishing work this run. it never lifts the park or the merge hold." # The maintainer owns direction, not the work (maintainer, 2026-11-13): no bound hands it over. @@ -66,11 +71,13 @@ skill_clauses=( "an upstream item closed without a released fix, or closed as not planned, still holds." "a blocker you cannot read, or a record that names none, never justifies unparking" "a mis-park is unparked and driven. at every check, confirm the pr really depends on its named blocker:" - "cannot be read, the pr is unknown: never settled, and never merged." + "cannot be read, the pr is unknown: never settled, and never merged. an age that cannot be read counts as past the bound." + "it clears once the decision is recorded in the park record and the change it requires is on the pr or merged." ) surveyor_clauses=( "a pr the consumer parked through its blocked-work mechanism stays in this section and in the digest with its pentad, like any other pr." "never omit it, or report it as finished, because it is parked." + "its classification, \`merge-ready\` included, covers the pentad only." "including that a parked pr is never merged while it is parked." ) # A sentence that would make any of the three read a park as settled, or hand it to the maintainer. @@ -81,6 +88,10 @@ forbidden_clauses=( "past a longer bound" # Dependabot security updates have their own open-PR limit, so a version-update stall never blocks them. "security fixes included" + # Broader forms of a handoff, so a reworded escalation still fails. + "hand the pr to the maintainer" + "escalate to the maintainer" + "goes to the maintainer" ) normalize() { diff --git a/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md b/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md index feb35111..2108f6d7 100644 --- a/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md +++ b/plugins/agentic-engineering/skills/portfolio-maintenance/references/driving-prs.md @@ -10,7 +10,8 @@ keeps only its summary. direct merge for your own promoted PRs; on merge-queue repos, root-cause a queue kick-out before re-queuing — a queued-but-unmerged PR has usually been evicted by a failed queue check). **Immediately before every merge in this path, re-read the current head and revalidate genuine - readiness; abort if any condition changed.** A layer of a stacked pull request merges only + readiness; abort if any condition changed.** Genuine readiness here includes that the PR is not + parked. A layer of a stacked pull request merges only bottom-first, one layer at a time, per [the stacked pull requests guide](../../product-engineering/references/stacked-pull-requests.md); never run `gh stack merge`. Keep @@ -56,14 +57,15 @@ keeps only its summary. **A parked PR is not a resting place.** Parking a PR through the deployment's blocked-work mechanism records why it cannot merge yet. It never settles the PR: a run that counts parked PRs as finished lets them strand for weeks while nobody works what holds them. The blocker a park - names is owned work, and these rules apply to every parked PR on every run that drives PRs. A PR - the consumer's contract designates automation-owned stays outside them, exactly as the survey - leaves it. A parked PR is never merged while it is parked: once its blocker verifiably clears, - lift the park through the same mechanism, then drive the PR to merge under the normal gates. A - park's age runs from when the PR was first parked, never from the latest relabel, so a re-park - keeps the earlier date and errs toward more work, never less. The deployment's park mechanism - supplies that date and the park record; keep every route, decision and re-check date in that one - record, edited in place. + names is owned work, and these rules apply to every parked PR on every run that drives PRs. They + cover only the PRs the **Trust gate** lets you drive. A PR the consumer's contract designates + automation-owned stays outside them, exactly as the survey leaves it. A parked PR is never merged + while it is parked. When you park a PR, disarm its auto-merge and take it out of any merge queue, + so the park holds the merge. Once its blocker verifiably clears, lift the park through the same + mechanism, then drive the PR to merge under the normal gates. A park's age runs from when the PR + was first parked, never from the latest relabel, so a re-park keeps the earlier date and errs + toward more work, never less. The deployment's park mechanism supplies that date and the park + record; keep every route, decision and re-check date in that one record, edited in place. - **An in-portfolio blocker is finishing work.** When the blocker is an issue, PR or decision inside the Portfolio map, rank it with your in-flight PRs, ahead of any new pull: claim it through the deployment's claim mechanism (its **Writer namespaces** or claim protocol) and work @@ -84,12 +86,17 @@ keeps only its summary. readiness gates. - **Past its bound, a parked dependency-update PR is yours to unblock by engineering.** Once it has been parked for 14 days, unless the **Cadence** names another bound, waiting is no longer a - route. Take an engineering route yourself, and keep taking them until the PR merges or is closed - for a recorded reason: adapt the product, fork or patch the dependency, isolate or replace the - conflicting dependency, contribute upstream, or split the update so the unblocked part merges. - Record in the park record what you tried and what it showed, the next route you will take, and - the date you will look again, at most one bound ahead. A missing or lapsed record makes taking - the next route finishing work this run. It never lifts the park or the merge hold. + route. Take an engineering route yourself, and keep taking them until the PR merges or a newer + update supersedes it: adapt the product, fork or patch the dependency (a fork goes through the + deployment's own repository-creation path), isolate or replace the conflicting dependency, + contribute upstream under the same procedure, or split the update so the unblocked part merges. + Closing it otherwise is the separate, deliberate decision to reject the update, never a way to + free a slot or clear the bound. A close the update tool records as an ignore is an ignore, and + is tracked as one. Record in the park record what you tried and what it showed, the next route + you will take, and the date you will look again. That date is at most one bound ahead, and + never later than the upstream re-check interval when the blocker is upstream. A missing or + lapsed record makes taking the next route finishing work this run. It never lifts the park or + the merge hold. - **Ownership stays with you.** You own the code and its dependency updates, never the maintainer. A park never hands work to the maintainer, and no timer or bound makes contacting the maintainer the outcome. Use the deployment's **Maintainer channels** only for a genuine @@ -108,11 +115,13 @@ keeps only its summary. named blocker: the change touches what the blocker names, and the blocker still holds. A blocker has cleared 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. A PR that verifiably does not depend on its blocker (the - wrong blocker, a cleared one, or one that holds only another part of a grouped update) is - unparked through the same mechanism and driven like any other PR. A scope or design decision - is a blocker too. A blocker you cannot read, or a record that names none, never justifies - unparking: repair or re-verify the record instead. + closed as not planned, still holds. A scope or design decision is a blocker too, and it clears + once the decision is recorded in the park record and the change it requires is on the PR or + merged. A PR that verifiably does not depend on its blocker (the wrong blocker, a cleared one, + or one that holds only another part of a grouped update) is unparked through the same mechanism + and driven like any other PR. A blocker you cannot read, or a record that names none, never + justifies unparking: repair or re-verify the record instead. A parked PR never leaves the survey. When its park facts (when it was parked, its blocker, its - latest route record) cannot be read, the PR is unknown: never settled, and never merged. + latest route record) cannot be read, the PR is unknown: never settled, and never merged. An age + that cannot be read counts as past the bound.