diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 082ae89..ef23601 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.7.0", + "version": "7.8.0", "source": "./plugins/agentic-engineering" }, { diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 082ae89..ef23601 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.7.0", + "version": "7.8.0", "source": "./plugins/agentic-engineering" }, { diff --git a/plugins/agentic-engineering/.claude-plugin/plugin.json b/plugins/agentic-engineering/.claude-plugin/plugin.json index b597fea..ec16d9a 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.7.0", + "version": "7.8.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 79deb5b..04aeb66 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.7.0", + "version": "7.8.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 bc6604c..f3d2c40 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -1,5 +1,31 @@ # Changelog — `agentic-engineering` +## 7.8.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, 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 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: 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 +the clauses. + ## 7.7.0 — 2026-11-13 **Added** — the `numina` MCP server, Numina's hosted server at `https://api.numina.app/mcp`. It diff --git a/plugins/agentic-engineering/README.md b/plugins/agentic-engineering/README.md index 58d6bc1..282e3b4 100644 --- a/plugins/agentic-engineering/README.md +++ b/plugins/agentic-engineering/README.md @@ -463,7 +463,9 @@ skills fail closed when any are absent: 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 ce411b4..0559cfc 100644 --- a/plugins/agentic-engineering/agents/agentic-engineer.agent.md +++ b/plugins/agentic-engineering/agents/agentic-engineer.agent.md @@ -140,7 +140,15 @@ 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). 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 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 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 d69e29d..ca7dcab 100644 --- a/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md +++ b/plugins/agentic-engineering/agents/portfolio-surveyor.agent.md @@ -311,6 +311,13 @@ included**, automation-owned dependency PRs excluded — report: - **(d) merge conflicts / behind-base state.** - **(e) green-review state** — see below. +**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. 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 conflicting, and it carries ≥1 green review. `mergeState` stays an independent merge gate. diff --git a/plugins/agentic-engineering/plugin.json b/plugins/agentic-engineering/plugin.json index b597fea..ec16d9a 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.7.0", + "version": "7.8.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 d86f413..d29ed5b 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": "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": "718e2058a2a547e108e807fabd53ccf7cf7ce7a21be37d7045ac4ba7c2d6f184" + "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 new file mode 100755 index 0000000..5cd896b --- /dev/null +++ b/plugins/agentic-engineering/scripts/parked-pr-ownership-contract.test.sh @@ -0,0 +1,206 @@ +#!/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" + "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 at or near its open-pr limit with any pr parked 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 (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." + "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." + "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." + "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." + "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 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. + "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:" + "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. +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" + # 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() { + 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 ... — 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 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 + 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 + } + } + } + ' "$dir/SKILL.md" >"$out" +} + +fail=0 +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 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