vouchington-tooling 0.50.0 → 0.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/scripts/gha/ghcr-main-history.sh

@@ -2,7 +2,17 @@
 # Sourced by ghcr-package-retention.sh for --main-history. Expects package_root, packages, apply,
 # keep_main and min_age_days from the caller.
 
+# shellcheck source=/dev/null
+. "$(dirname "${BASH_SOURCE[0]}")/ghcr-referenced-digests.sh"
+
 prune_main_history() {
+  # The registry namespace of the packages: GHCR_OWNER, else the workflow's repository owner.
+  local owner="${GHCR_OWNER:-${GITHUB_REPOSITORY_OWNER:-}}"
+  if [ -z "$owner" ]; then
+    echo '::error::ghcr-package-retention: GHCR_OWNER is required with --main-history' >&2
+    exit 2
+  fi
+
   # A zero keep count would delete every main image in one run.
   case "$keep_main" in
     '' | *[!0-9]*) keep_main=0 ;;
@@ -49,10 +59,13 @@ prune_main_history() {
       | min) as $oldest_image
     | ($versions | map(select(attachment and idle and $oldest_image != null
         and created < $oldest_image - 86400) | . + {reason: "orphan"})) as $orphans
-    | ($old_main + $unmerged + $orphans)[]
-    | "\(.id) \(tags | if length == 0 then "<untagged>" else join(",") end) \(.reason)"'
+    | {roots: ($versions | map(select((attachment | not) and (.id | IN($doomed[]) | not)) | .name)),
+       candidates: ($old_main + $unmerged + $orphans | map({id, name, reason,
+         tags: (tags | if length == 0 then "<untagged>" else join(",") end)}))}'
+  local filter='.candidates | map(select(.name | IN($referenced[]) | not))[]
+    | "\(.id) \(.tags) \(.reason)"'
 
-  local deleted_total=0 package path error deletions id tags reason
+  local deleted_total=0 package path error deletions id tags reason referenced image resolved
   for package in "${packages[@]}"; do
     path="$package_root/$package/versions"
     if ! error=$(gh api --paginate "$path?per_page=100" 2>&1 > "$work/pages"); then
@@ -67,8 +80,18 @@ prune_main_history() {
       exit 1
     fi
 
-    deletions=$(jq -r -s --rawfile revisions "$work/main-revisions" --argjson keep "$keep_main" \
-      --argjson cutoff "$cutoff" "$plan" "$work/pages")
+    jq -s --rawfile revisions "$work/main-revisions" --argjson keep "$keep_main" \
+      --argjson cutoff "$cutoff" "$plan" "$work/pages" > "$work/plan"
+    # Never delete a digest that a kept image or index still references (platform manifests,
+    # attestations, subjects). An unreadable kept manifest aborts rather than risk a delete.
+    referenced='[]'
+    if [ "$(jq '.candidates | length' "$work/plan")" -gt 0 ]; then
+      jq -r '.roots[]' "$work/plan" > "$work/roots"
+      image="$owner/$(printf '%b' "${package//%/\\x}")"
+      resolved=$(resolve_referenced "$image" "$owner" "$work" "$work/roots") || exit 1
+      referenced=$(printf '%s\n' "$resolved" | jq -R . | jq -s .)
+    fi
+    deletions=$(jq -r --argjson referenced "$referenced" "$filter" "$work/plan")
     echo "· $package: $(jq -s 'add // [] | length' "$work/pages") version(s)"
     while read -r id tags reason; do
       [ -n "$id" ] || continue

package/scripts/gha/ghcr-package-retention.sh

@@ -12,6 +12,10 @@
 # - An attachment: untagged or tagged only sha256-*. Attestations and their referrer indexes are
 #   pushed after their image, and platform manifests moments before it, so an attachment created
 #   over a day before the oldest surviving image, and idle for the same age, belongs to none.
+# Before deleting, the manifests of every surviving image are read from the registry (GH_TOKEN or
+# GITHUB_TOKEN, else gh auth token) and anything they reference through manifests[] or subject is
+# kept; if one cannot be read, the package is left untouched. The registry namespace is GHCR_OWNER,
+# else GITHUB_REPOSITORY_OWNER (required for user-owned packages too).
 # Packages that do not exist (HTTP 404) are skipped. Defaults to a dry run; pass --apply to delete.
 #
 # Packages come from the arguments, or from GHCR_PACKAGES (space separated) when none are given.

package/scripts/gha/ghcr-referenced-digests.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Sourced by ghcr-main-history.sh. Walks OCI manifests through manifests[] and subject.
+
+# registry_token <image> <owner> <work-dir>: exchanges the GitHub token for a registry pull token
+# (GHCR's documented /token endpoint, Basic auth) and prints it. Credentials go to curl on stdin.
+registry_token() {
+  local image="$1" owner="$2" dir="$3" token registry
+  registry="${GHCR_REGISTRY_URL:-https://ghcr.io}"
+  token="${GH_TOKEN:-${GITHUB_TOKEN:-}}"
+  if [ -z "$token" ]; then
+    token=$(gh auth token) || {
+      echo '::error::No GH_TOKEN or GITHUB_TOKEN, and gh auth token failed' >&2
+      return 1
+    }
+  fi
+  if ! printf 'user = "%s:%s"\n' "$owner" "$token" |
+    curl -fsS -K - "$registry/token?scope=repository:$image:pull" \
+      > "$dir/token.json" 2> "$dir/curl-error"; then
+    printf '::error::Could not get a registry token for %s: %s\n' "$image" \
+      "$(cat "$dir/curl-error")" >&2
+    return 1
+  fi
+  jq -er '.token | select(type == "string" and . != "")' "$dir/token.json" || {
+    printf '::error::Registry token response for %s had no token\n' "$image" >&2
+    return 1
+  }
+}
+
+# resolve_referenced <image> <owner> <work-dir> <roots-file>: prints every digest reachable from
+# the root digests (one per line in the file), roots included. Returns non-zero on any failure, so
+# the caller deletes nothing.
+resolve_referenced() {
+  local image="$1" owner="$2" dir="$3" digest registry_bearer registry accept
+  registry="${GHCR_REGISTRY_URL:-https://ghcr.io}"
+  registry_bearer=$(registry_token "$image" "$owner" "$dir") || return 1
+  accept='application/vnd.oci.image.index.v1+json'
+  accept="$accept,application/vnd.oci.image.manifest.v1+json"
+  accept="$accept,application/vnd.docker.distribution.manifest.list.v2+json"
+  accept="$accept,application/vnd.docker.distribution.manifest.v2+json"
+
+  : > "$dir/seen"
+  cp "$4" "$dir/queue" || return 1
+  while [ -s "$dir/queue" ]; do
+    digest=$(head -n 1 "$dir/queue")
+    sed -i.bak 1d "$dir/queue" || return 1
+    rm -f "$dir/queue.bak"
+    [ -n "$digest" ] || continue
+    ! grep -qxF "$digest" "$dir/seen" || continue
+    echo "$digest" >> "$dir/seen"
+    if ! printf 'header = "Authorization: Bearer %s"\n' "$registry_bearer" |
+      curl -fsS -K - -H "Accept: $accept" "$registry/v2/$image/manifests/$digest" \
+        > "$dir/manifest" 2> "$dir/curl-error"; then
+      printf '::error::Could not read manifest %s of %s: %s\n' "$digest" "$image" \
+        "$(cat "$dir/curl-error")" >&2
+      return 1
+    fi
+    if ! jq -r '[(.manifests // [])[].digest, (.subject.digest // empty)] | .[]' \
+      "$dir/manifest" >> "$dir/queue" 2> "$dir/jq-error"; then
+      printf '::error::Could not parse manifest %s of %s: %s\n' "$digest" "$image" \
+        "$(cat "$dir/jq-error")" >&2
+      return 1
+    fi
+  done
+  cat "$dir/seen"
+}

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "agent-workflow/SKILL.md",
       "prerequisites": [
         "blackboard",
@@ -24,7 +24,7 @@
     {
       "name": "blackboard",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "blackboard/SKILL.md"
     },
     {
@@ -36,7 +36,7 @@
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "dependabot/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -50,26 +50,26 @@
     {
       "name": "git-commit-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "github-issue/SKILL.md"
     },
     {
@@ -82,26 +82,26 @@
     {
       "name": "npm-publishing",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "npm-publishing/SKILL.md"
     },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "organize-github-issues/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "planning/SKILL.md",
       "prerequisites": ["github-issue"]
     },
@@ -133,53 +133,53 @@
     {
       "name": "pr-description",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "retrospective-distill/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "review-ci-logs/SKILL.md",
       "prerequisites": ["github-actions-checklist", "pr-description"]
     },
     {
       "name": "review-github-issue-taxonomy",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "review-github-issue-taxonomy/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "revisit-followups/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "stacked-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "stacked-prs/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.12.0",
+      "pluginVersion": "0.13.0",
       "path": "static-analysis-checklist/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -203,6 +203,19 @@
       "pluginVersion": "0.2.0",
       "path": "test-authoring/SKILL.md"
     },
+    {
+      "name": "triage-prs",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.13.0",
+      "path": "triage-prs/SKILL.md",
+      "prerequisites": [
+        "pr-description",
+        "retrospective",
+        "review-ci-logs",
+        "github-issue",
+        "stacked-prs"
+      ]
+    },
     {
       "name": "vitest-test-authoring",
       "plugin": "vouchington-testing",

package/skills/triage-prs/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: triage-prs
+description: Review the PR queue and merge or close PRs under the user's triage authorization.
+---
+
+# Triage pull requests
+
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/triage-prs/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
+Review open pull requests, merge the good ones, and close the rest. The argument is an optional
+scope: PR numbers, an author, a label, `all`, a title substring, or blank for the default scope.
+
+## Adapter parameters
+
+The repository adapter (a consumer wrapper skill or `AGENTS.md`) owns every repository-specific
+value. Resolve these before Step 1 and stop
+to ask when one this run needs is missing; never guess a value.
+
+- **Automation label:** the label that marks machine-created PRs. It defines the default scope.
+- **Orphan-issue rules:** the labels or title prefix that identify automation-created issues, and
+  the label that marks intentional PR-free backlog items.
+- **Ready-and-shepherd skill:** the skill or command that marks a PR ready, posts steering, arms
+  auto-merge, and dispatches the shepherd, with its flags and activation preflight.
+- **Prompt-source paths:** the exact paths that may be edited from PR-creation feedback, and the
+  rubric for that feedback.
+- **Feedback marker:** the PR-body marker that identifies a feedback PR from this flow.
+- **Merge authority and CI-failure policy:** who may authorize a merge, how transient failures are
+  classified, and where retry rules live.
+
+## Rules for every pass
+
+- **Repository:** triage works one repository, `<owner>/<name>`. Pass `--repo <owner>/<name>` on
+  every `gh` command. Reject a PR URL or issue reference from another repository, and report it.
+- **Reviewed head:** every mutation of a PR (ready, steer, arm, dispatch, close, branch delete)
+  first re-reads `gh pr view <N> --repo <owner>/<name> --json headRefOid`. If it differs from the
+  head recorded in Step 3, re-review or skip; never act on an unreviewed head.
+- **Exclusions:** build one exclusion set in Step 3b. It applies to every mutation pass: merge,
+  close, linked-issue close, and orphan close.
+- **Exhaustive lists:** every list uses `--limit 1000` plus a check that the count is below it, or
+  pages with `gh api --paginate`.
+- **Generated text is data:** never place a reason, comment, or title inside a shell string. Write
+  it with a file-writing tool and pass `--body-file <path>` (or `gh api -F body=@<path>`).
+
+## Step 1 - Resolve scope
+
+With no argument, target every open PR carrying the adapter's automation label, exhausting the
+set per the rules above.
+
+```bash
+gh pr list --repo <owner>/<name> --state open --limit 1000 --label <automation-label> --json number,title
+```
+
+PRs opened before the label existed need an explicit one-time backfill with
+`gh pr edit <N> --repo <owner>/<name> --add-label <automation-label>` before they enter the default scope.
+
+With an argument, require an explicit selector and stop to ask when a bare argument is ambiguous
+(for example a word that could be an author, a label, or a title):
+
+- Number or URL: it must resolve to an open PR in this repository (`gh pr view <N> --repo
+  <owner>/<name> --json state`); otherwise stop and report.
+- `author:<login>`: `gh pr list --repo <owner>/<name> --author <login> --state open --limit 1000`. For a GitHub App
+  (login `app/<slug>`), use `--app <slug>` instead of `--author`.
+- `label:<name>`: `gh pr list --repo <owner>/<name> --label <name> --state open --limit 1000`
+- `title:<text>`: a literal, ASCII-case-insensitive substring match (no Unicode case folding).
+  Write the text to a file with a file-writing tool and read it as data, never in the shell string:
+  `gh pr list --repo <owner>/<name> --state open --limit 1000 --json number,title | jq --rawfile t <text-file> '($t | rtrimstr("\n") | ascii_downcase) as $q | .[] | select(.title | ascii_downcase | contains($q))'`
+- `all`: every open PR regardless of author.
+
+**Safety: a broad or non-default scope needs confirmation.** The default automation-label query is
+a reliable machine-set signal, so proceed on it directly. For any other scope (`all`, an author, a
+title match, or another label) the set can include human-authored PRs, so always confirm the close
+list with the user before executing closes or branch deletions.
+
+## Step 2 - Gather status
+
+Fetch CI rollup and diff sizes for the in-scope PR numbers only. Do not re-fetch all open PRs:
+a broader list pulls out-of-scope PRs into the review and close queues.
+
+```bash
+gh pr view <N> --repo <owner>/<name> --json number,title,isDraft,additions,deletions,changedFiles,statusCheckRollup
+```
+
+Run one call per PR, or filter one `gh pr list --json ...` result with
+`jq '.[] | select(.number | IN(<N1>,<N2>,...))'` when the set is large.
+
+## Step 3 - Review and steering assessment
+
+Batch the in-scope PRs across up to three parallel read-only agents. Each reads the PR
+description and full diff, loads [review-ci-logs](../review-ci-logs/SKILL.md) for failing required
+checks, and returns per PR:
+
+- **Head:** the reviewed `headRefOid`, bound to the diff: read `gh pr view <N> --repo <owner>/<name>
+  --json headRefOid` before and after fetching the diff, and accept the review only when both
+  values match; otherwise repeat it
+- **Decision:** `MERGE` or `CLOSE`
+- **Reason:** a one-line summary
+- **Steering:** (MERGE only) whether the shepherd needs direction, and the exact PR comment body
+- **PR creation feedback:** for verified agent-authored PRs, apply the adapter's rubric and return
+  evidence, provenance, the exact source target, a recommendation, and a recurrence tag;
+  otherwise `none`
+
+Each agent reads with `gh pr view <N>`, `gh pr diff <N>` (both with `--repo`), and the repository's CI check listing.
+
+See [the default rubric](references/rubric.md) for MERGE versus CLOSE, generalizing a narrow
+band-aid before closing it, and the shape of steering comments. The user's session steering
+overrides the rubric, including flipping a green PR to CLOSE; present it as context.
+
+## Step 3b - Build the exclusion set
+
+Before any mutation, resolve [feedback duplicates](references/feedback.md#duplicate-resolution).
+Every feedback PR this run generates or reuses, and its source issue, joins the exclusion set. A
+member is never readied, shepherded, armed, merged, closed, or branch-deleted, and its issue is
+never closed, in this run, whatever its Step 3 decision.
+
+## Step 4 - Execute MERGE
+
+Skip excluded PRs and re-check the reviewed head per the rules. Carry each root-cause follow-up
+from the [rubric](references/rubric.md) (an issue to file, link, or re-scope) into this pass and
+the Step 6 report so it is not dropped. Process MERGE decisions in
+ascending PR-number order through the adapter's ready-and-shepherd
+skill, passing the PR number, the auto-merge flag, and any steering file. That skill light-reviews
+the diff, posts steering before the trigger, readies the draft, verifies merge settings, and
+dispatches the shepherd. Run its activation preflight before every mutation. If activation is
+disabled, unset, or unreadable, record `activation disabled - unchanged` and do not describe the PR
+as ready, armed, or dispatched.
+
+Classify the outcome:
+
+- **Unsteered and arming succeeds:** already armed. Auto-merge may complete once requirements pass
+  while the asynchronous shepherd independently checks the PR.
+- **Steered, or arming fails on a conflict:** leave the PR ready and unarmed after dispatch.
+  Dispatch is fire-and-forget; a `running` checkpoint proves session acceptance, not success. A
+  human inspects the eventual state and decides whether to arm auto-merge. Do not wait for or infer
+  a `complete` checkpoint.
+- **Repository auto-merge disabled:** dispatch the shepherd, report that a manual merge is
+  required, and leave auto-merge unchanged.
+- **Native GitHub stack:** shepherd the owned layers per
+  [stacked-prs](../stacked-prs/SKILL.md#ownership-and-workers) and merge the ready prefix per
+  [Merge the ready prefix](../stacked-prs/SKILL.md#merge-the-ready-prefix), within explicit human
+  approval and only as far as this run's decisions cover. Resolve the full stack against the Step 1
+  scope and Step 3 decisions first. End the ready prefix below the first layer that is out of scope
+  or not `MERGE`; never shepherd or merge a layer this run did not review. GitHub has no
+  auto-merge for stacks, and an armed auto-merge does not authorize the drain on its own.
+
+Do not add a second pass that polls the dispatch workflow. It ends once the session is accepted or
+rejected and cannot attest that the remote agent consumed steering or left the branch mergeable.
+
+## Step 5 - Execute CLOSE
+
+Skip excluded PRs and re-check the reviewed head per the rules. Write the one-line reason to a file
+with a file-writing tool, then comment from the file and close:
+
+```bash
+gh pr comment <N> --repo <owner>/<name> --body-file <reason-file>
+gh pr close <N> --repo <owner>/<name>
+```
+
+Report every close that kept its branch, with the reason. Branch deletion, linked-issue closes, and orphan automation issues (default scope only) follow the
+[close procedure](references/close.md).
+
+## Step 6 - Verify and report
+
+Check that merge and close actions landed:
+
+```bash
+gh pr view <N> --repo <owner>/<name> --json isDraft,autoMergeRequest,state
+```
+
+Emit a summary table with the columns PR, Decision, Action, and Steering. Actions are
+`ready + shepherd + auto-merge armed`, `ready + shepherd, manual verification required`,
+`ready + shepherd, manual merge required`, `activation disabled - unchanged`, and
+`closed + branch deleted`.
+
+After Steps 4 and 5, amend the Step 3 creation feedback with action-time steering and CI evidence.
+Do not wait for the newly dispatched shepherd; record only evidence available during this run.
+Then publish [preauthorized prompt feedback](references/feedback.md), group the recommendations by
+root cause, and invoke [retrospective](../retrospective/SKILL.md) before the final report.

package/skills/triage-prs/references/close.md

@@ -0,0 +1,83 @@
+# Close procedure
+
+Applies the rules in `SKILL.md`: explicit `--repo`, reviewed head re-check, the exclusion set,
+exhaustive lists, and generated text passed only from files.
+
+## Delete the branch
+
+`gh pr close` does not delete the branch unless asked, and merge-time auto-deletion does not apply
+to closes. Read the head branch name and head repository as data (`gh pr view <N> --repo <owner>/<name>
+--json headRefName,headRepository,headRepositoryOwner`) and pass them to `jq --arg`, never into a
+shell string. Before deleting, find every open PR that depends on the branch:
+
+```bash
+gh pr list --repo <owner>/<name> --state open --limit 1000 \
+  --json number,title,baseRefName,headRefName,headRepository,headRepositoryOwner \
+  | jq --arg b "$BRANCH" --arg r "$HEAD_REPO" '.[] | select(.baseRefName == $b or (.headRefName == $b and .headRepository.name == $r))'
+gh search prs --state open --limit 1000 --owner <owner> --head "$BRANCH" --json url,repository
+```
+
+The first query includes PRs from forks that target this branch (they appear under `--repo`), and
+PRs sharing the head. The second finds PRs in other repositories that use this branch as their
+head. Ignore the PR being closed. If any other PR remains, or cross-repository reuse cannot be ruled
+out, do not delete the branch: deleting a base closes its dependents, including unreviewed layers,
+and deleting a shared head closes the others. Close without deleting and report the PR and why the
+branch was kept. Otherwise close with `gh pr close <N> --repo <owner>/<name> --delete-branch` in
+place of the plain close in Step 5.
+
+## Linked issues
+
+```bash
+gh pr view <N> --repo <owner>/<name> --json closingIssuesReferences \
+  --jq '.closingIssuesReferences[] | {number, title, url, repository}'
+```
+
+Keep each reference's repository and URL. Close only issues in this repository; skip and report
+cross-repository targets. Close an issue only if it appears automation-created under the adapter's
+orphan-issue rules. Skip anything that looks human-authored: automation sometimes reuses a
+human-tracked issue by adding `Closes #<N>` to a PR body. Skip excluded issues. Before closing,
+re-read the issue (`gh issue view <ISSUE_N> --repo <owner>/<name> --json state,labels,title`) and
+confirm it is still open and still classified as automation-created; then
+apply the [no-open-PR checks](#no-open-pr-checks), excluding the PR just closed.
+
+Write the comment (`Closing alongside PR #<N>: <reason>`) to a file, then:
+
+```bash
+gh issue comment <ISSUE_N> --repo <owner>/<name> --body-file <comment-file>
+gh issue close <ISSUE_N> --repo <owner>/<name>
+```
+
+## Orphan automation issues
+
+Default scope only. Skip this for narrow-scope runs: scanning the full issue queue would close
+issues unrelated to the PRs actually triaged.
+
+Find open automation issues with no open linked PR: issues whose PR was never opened, was merged or
+closed separately, or was just closed. Identify them with the adapter's orphan-issue rules, exclude
+the adapter's PR-free backlog label (intentional human-escalation items), and exclude the exclusion
+set. Exhaust the list:
+
+```bash
+gh issue list --repo <owner>/<name> --state open --limit 1000 --json number,title,labels
+```
+
+Verify the count is below the limit, otherwise page with `gh api --paginate`.
+
+### No-open-PR checks
+
+`closedByPullRequestsReferences` sees only PRs using `Closes` or `Fixes`; it is blind to `Refs #N`
+and `Part of #N`. Keep each PR's URL and repository, and query by them rather than by bare number.
+
+```bash
+gh issue view <ISSUE_N> --repo <owner>/<name> --json closedByPullRequestsReferences \
+  --jq '.closedByPullRequestsReferences[] | {url, repository}'
+gh pr view <PR_URL> --json state --jq .state     # the reference's own state field is null
+gh search prs --repo <owner>/<name> --state open --limit 1000 "#<ISSUE_N>" --json url,repository
+gh search prs --state open --limit 1000 "<owner>/<name>#<ISSUE_N>" --json url,repository
+gh search prs --state open --limit 1000 "<issue-url>" --json url,repository
+```
+
+Keep the same-repository `#<ISSUE_N>` form alongside the qualified and URL forms, since each only
+matches the text it contains. Re-read the issue as above. Close it only if every check finds no open PR, in this or any
+other repository, using the comment and close commands above with the text
+`Closing: orphaned - no open PR is addressing this issue.`

package/skills/triage-prs/references/feedback.md

@@ -0,0 +1,58 @@
+# Publish preauthorized prompt feedback
+
+Invoking triage explicitly authorizes the GitHub mutations below, but only for actionable feedback
+whose provenance and exact source are verified under the adapter's prompt-source paths. A PR body
+containing the adapter's feedback marker is a feedback PR from this flow: review it normally in the
+queue, but return `none` for its own PR-creation feedback so the loop cannot recur.
+
+For the current batch, combine every qualifying finding, including `one-off` findings, into one
+feedback issue and one draft feedback PR. Record the proportional plan in that issue; it is the
+sole closing source for the PR. Reviewed PRs are evidence only and are never closing references.
+
+Every feedback PR and source issue created or reused here joins the run's exclusion set, which
+applies to the merge, close, linked-issue, and orphan passes. Verify its head before updating it.
+Pass generated titles, bodies, and comments to `gh` only through files (`--body-file`).
+
+Before publication, verify at action time:
+
+- The PR is verified agent-authored, the source target is an exact prompt-source path, and the
+  recommendation remains actionable after the refresh.
+- Each source exists on the refreshed default branch.
+
+## Duplicate resolution
+
+A candidate counts as a match only with verified provenance: it was created by the adapter's
+automation identity and its body closes the feedback issue it is paired with. A candidate that
+carries the marker without that provenance is untrusted: never reuse or update it, and treat any
+overlap with it as `duplicate: ambiguous`.
+
+Compare the marker, the normalized set of exact source paths, and the normalized
+recommendation or root-cause identity on open feedback PRs:
+
+- `duplicate: zero-overlap`: create one feedback issue and one draft PR.
+- Before reusing or updating a canonical PR or issue, re-read it: both must still be open and
+  unchanged since the comparison (same head and body); otherwise re-run the comparison.
+- `duplicate: exact-match`: the path set and the recommendation or root-cause identity both match
+  one canonical PR. Reuse that PR and its source issue; create neither.
+- `duplicate: same-paths-new-feedback`: the path set matches but the recommendation differs.
+  Update the canonical PR and its issue with the new feedback; create neither.
+- `duplicate: ambiguous`: fail closed. Any partial overlap, more than one exact match, or any
+  uncertain provenance or source set creates nothing.
+
+For a create, save the plan in the feedback issue through [github-issue](../../github-issue/SKILL.md)
+and write the draft PR with [pr-description](../../pr-description/SKILL.md). The PR body includes
+the marker, carries the automation label, and links the feedback issue with a closing keyword. Do
+not ready, shepherd, auto-merge, or merge a generated or reused feedback PR in the same run.
+
+## Retrospective disposition
+
+- `disposition: published`: record `Disposition: preauthorized-pr #N` after a successful create,
+  exact-match reuse, or `same-paths-new-feedback` update of the canonical PR and issue.
+- `disposition: deferred`: record `deferred` with the concrete blocker after a failed, partial, or
+  ambiguous publication. Do not ask the user or claim the feedback was handled.
+- `disposition: user-choice`: keep non-prompt feedback in the normal human follow-up flow.
+
+Group the Step 3 PR-creation recommendations by root cause and invoke
+[retrospective](../../retrospective/SKILL.md). It records findings for merged and closed PRs alike.
+Preserve `none` when no actionable generator improvement was found, and complete this flow before
+the final triage report.

package/skills/triage-prs/references/rubric.md

@@ -0,0 +1,61 @@
+# Default triage rubric
+
+This rubric is a default, not a law. Session steering from the user overrides it.
+
+- **MERGE:** a real bugfix, a general root-cause fix, or a safe chore. A CI failure caused by the
+  PR's own change is fine; the shepherd drives it green. A merge conflict (`CONFLICTING` or
+  `DIRTY`) does not by itself warrant a close. If the fix is good on the merits, salvage it through
+  the MERGE path: ready it, arm auto-merge, and let the shepherd rebase, resolve, and drive CI
+  green. Salvage by default without asking the user.
+- **CLOSE:** a narrow per-fingerprint band-aid (prefer general solutions), stale, superseded, or
+  scope already landed on the default branch. Close a conflicting branch only when it is also one
+  of those; never close a good fix solely because it conflicts.
+
+## Before closing a narrow band-aid, ask whether it generalizes
+
+A per-fingerprint band-aid often points at a root cause worth a general fix. Diagnose the failure
+it papers over first. Is it:
+
+- **repository-owned:** the repository's own code, config, or infrastructure, such as a step
+  timeout, a permissions policy, a build toolchain, or a lock or port collision in its scripts;
+- **deterministic:** it hits a fixed budget or limit. Litmus test: rerun the identical job
+  unchanged; if it hits the same wall every time, raise the limit, remove the bottleneck, or
+  restructure the work; or
+- **transient:** the same input sometimes passes, such as an intermittent race, a propagation
+  delay, or a genuinely external 5xx or rate limit?
+
+Only the transient case justifies broadening a retry rule. Repository-owned and deterministic
+failures make a retry rule invalid; the fix is the root cause.
+
+- **Anti-fork:** never hardcode a concrete resource address (an ARN, a bus name, a batch id) into a
+  fingerprint. Broaden the existing consumer-by-root-cause rule instead of forking one per action,
+  status, or URL, following the adapter's retry-rule policy. A rule that hardcodes one resource
+  re-fails the moment a different resource hits the same race.
+- **Hard cases:** when a failure cannot be classified (no rerun-success evidence either way),
+  never add or bump a retry rule as a substitute for classification. Fix the best-supported cause
+  and capture the evidence the next occurrence needs, per the adapter's CI-failure policy.
+- **Treadmill signature:** a rule whose attempt limit is bumped again on a later PR for the same
+  consumer and root-cause pair, without the cause changing. That pair is repository-owned and was
+  mis-elevated the first time; bumping it again repeats the mistake.
+- **Elevate, do not hide:** a repository-owned cause must file or link a root-cause issue as part
+  of the disposition, reusing an open issue for the same pair rather than duplicating it. A PR
+  whose follow-ups say `None` while the cause is repository-owned is a signal to push back. For
+  deterministic and repository-owned failures, close the band-aid and file a follow-up issue for
+  the general fix under [github-issue](../../github-issue/SKILL.md), or re-scope an existing one.
+  Generalize-or-elevate beats a plain close.
+
+## What steering looks like
+
+When a MERGE PR needs shepherd direction, write the exact reviewed comment body to a temporary file
+with a file-writing tool, then read it back in full. Do not build the file with shell
+interpolation, a heredoc, `echo`, or `printf`: file-based input keeps shell metacharacters and
+backticks in reviewed steering from being expanded. Pass the file to the ready-and-shepherd skill
+so it posts a separate ordinary PR comment before the shepherd trigger.
+
+Examples:
+
+- `Prefer the general timeout-bound solution over a transient-retry rule.`
+- `The lint error is self-inflicted. Fix it first, then continue.`
+- `Do not add a new catalogue rule. Fix the underlying race condition instead.`
+- `This deadlock is transient. Broaden the matcher rather than closing the rule.`
+- `This timeout is deterministic, not transient. Close the narrow rule and open a root-cause issue.`