Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/contracts/upstream-drift/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,17 @@ Notable changes to the upstream-drift contract (SemVer). Changing a required par
name, or an enforceability verdict is a major bump; additive guidance is a minor bump; docs-only
clarification is a patch.

## [6.3.0] - 2026-11-16

Changed guidance; minor under this contract's own rule. No required part, canonical name, or
enforceability tier changes.

The filer no longer labels a created or reopened drift issue `needs-human`, by the owner's
standing direction that holds against our own actors come off (section 10, re-stated 2026-11-16):
a drift issue is an agent's re-audit, not an owner decision. A reopen no longer adds a label before
it reopens, and removes the `needs-human` an issue filed before this change kept through its close. Drift issues still enter no intake run on their own; the "No hold label" bullet says
what starts the re-audit.

## [6.2.0] - 2026-11-16

Changed guidance; minor under this contract's own rule. No required part, canonical name, or
Expand Down
20 changes: 9 additions & 11 deletions docs/contracts/upstream-drift/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -512,17 +512,15 @@ After a failed write the other upstreams still run, and the run then exits nonze
skill (`<plugin>:<skill>` from a `plugins/<plugin>/skills/<skill>/` path, else the id) and tells
the reader to run the page's path, restore or re-vendor what it names, and read its output in
the run's job summary. The re-audit footer is written only when a hex-pin page drifted.
- **`needs-human` on create and reopen.** A created issue carries the `needs-human` label. A
reopen adds the label first, then reopens, then replaces the body, so a failed reopen leaves a
labeled closed issue and a failed label add leaves the issue closed. An in-place edit of an open
issue adds no label. Removing `needs-human` does not admit a bot-authored issue to the issue
lane: the lane starts only when a listed person or the lanes App sets the issue's Work status to
agent-ready, and an issue this workflow's token opens starts no intake run. The label holds the
issue until a listed human lifts it, as the
[loop-lane label table](../loop-lane/README.md) says for `needs-human`. Lifting it and setting
Work status to agent-ready hands the issue to an agent for the re-audit described below; neither
step asks that person to mark each upstream change, and only a change to a skill's design comes
back to the owner.
- **No hold label.** The filer adds no label on create, reopen or edit: a drift issue is not an
owner decision, so it carries no `needs-human`, and a re-audit pull request that closes it meets
no `needs-human` hold at merge. A reopen reopens, then replaces the body and removes any
`needs-human` an earlier filer left, so a failed reopen leaves the closed issue unchanged. The issue still does not enter the issue lane on its
own: an issue this workflow's token opens starts no intake run, the hourly triage sweep skips
github-actions[bot] issues because some quote fork-controlled text, and admission counts only
done-when text a listed human wrote. A session agent, or a listed human's issue naming the drift
issues, starts the re-audit described below; only a change to a skill's design comes back to the
owner.
- **`untracked` and `unreachable` block close.** An upstream with any `untracked` or
`unreachable` page is never closed as clean,
even beside a `clean` page, and since the report names it, the sweep leaves its issue alone too.
Expand Down
13 changes: 5 additions & 8 deletions scripts/upstream-drift-issues.sh
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@
# span with backticks replaced. The re-audit footer is written only when a
# hex-pin page drifted. The body is cut at 60,000 characters with a pointer to
# the run's job summary, written to a temp file and passed with --body-file.
# A created or reopened issue gets the `needs-human` label, added before the
# reopen; an in-place edit adds no label. No assignees or mentions.
# No run adds a label; a reopen removes `needs-human` with its body edit. No
# assignees or mentions.
#
# The whole report is parsed before any gh call. Each line follows the fixed
# field order of the report (docs/contracts/upstream-drift/README.md, the
Expand Down Expand Up @@ -262,7 +262,7 @@ for i in "${!REPOS[@]}"; do
case "$action" in
create)
write_body "$i" "$body_file"
if url="$(gh issue create --title "$title" --body-file "$body_file" --label needs-human)"; then
if url="$(gh issue create --title "$title" --body-file "$body_file")"; then
[[ "$url" =~ /issues/([0-9]+)$ ]] && ! gh api -X PATCH "repos/{owner}/{repo}/issues/${BASH_REMATCH[1]}" -f type=Task >/dev/null &&
printf '%s: could not set the Issue Type on %s\n' "$SELF" "$url" >&2
else
Expand All @@ -275,12 +275,9 @@ for i in "${!REPOS[@]}"; do
;;
reopen)
write_body "$i" "$body_file"
# The label goes on first, so no reopened issue is ever unlabeled.
if ! gh issue edit "$num" --add-label needs-human >/dev/null; then
fail "label add failed for $repo"
elif ! gh issue reopen "$num" >/dev/null; then
if ! gh issue reopen "$num" >/dev/null; then
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
fail "issue reopen failed for $repo"
elif ! gh issue edit "$num" --body-file "$body_file" >/dev/null; then
elif ! gh issue edit "$num" --body-file "$body_file" --remove-label needs-human >/dev/null; then
fail "issue edit failed for $repo"
fi
;;
Expand Down
32 changes: 20 additions & 12 deletions scripts/upstream-drift-issues.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,13 @@ expect_lacks "create: unchanged rows are left out" "$body" 'skills/gamma'
expect_has "create: body names the pin" "$body" "\`$PIN\`"
expect_has "create: body names the head" "$body" "\`$HEAD\`"
expect_has "create: body names the run URL" "$body" 'https://github.com/acme/site/actions/runs/777'
expect_has "create: the issue gets the needs-human label" "$c" '--label needs-human'
create_call="$(grep '^issue create ' <<<"$c")"
if [[ "$create_call" =~ ^'issue create --title Upstream drift: acme/widgets --body-file '[^\ ]+$ ]]; then
pass "create: the create call carries only the title and body file, so no needs-human hold"
else
bad "create: the create call carries only the title and body file, so no needs-human hold" "$create_call"
fi
expect_lacks "create: no label is added" "$c" 'label'
expect_lacks "create: no assignee flag" "$c" '--assignee'

# --- a report with no unknown token keeps the record body byte for byte ------
Expand Down Expand Up @@ -268,10 +274,16 @@ expect_has "reopen: replaces its body from a body file" "$c" 'issue edit 12 --bo
expect_lacks "reopen: creates nothing" "$c" 'issue create'
expect_has "reopen: reports the action" "$OUT" 'action=reopen repo=acme/widgets'
expect_has "reopen: the body lists the changed row" "$(body_of edit)" '`skills/alpha/SKILL.md`'
if [[ "$c" == *'issue edit 12 --add-label needs-human'*'issue reopen 12'*'issue edit 12 --body-file'* ]]; then
pass "reopen: labels, then reopens, then edits the body"
if [[ "$c" == *'issue reopen 12'*'issue edit 12 --body-file'* ]]; then
pass "reopen: reopens, then edits the body"
else
bad "reopen: labels, then reopens, then edits the body" "$c"
bad "reopen: reopens, then edits the body" "$c"
fi
expect_lacks "reopen: no label is added" "$c" 'add-label'
if grep -Eq '^issue edit 12 --body-file [^ ]+ --remove-label needs-human$' <<<"$c"; then
pass "reopen: the body edit strips a needs-human hold left from before"
else
bad "reopen: the body edit strips a needs-human hold left from before" "$c"
fi
closed_list 'null'
run_sut "$DRIFT"
Expand Down Expand Up @@ -388,7 +400,7 @@ run_sut "$VENDORED"
expect_code "unknown pin: accepted, exit 0" 0
c="$(calls)"
expect_has "unknown pin: creates the id's issue" "$c" 'issue create --title Upstream drift: playwright/playwright --body-file'
expect_has "unknown pin: the issue gets the needs-human label" "$c" '--label needs-human'
expect_lacks "unknown pin: no label is added" "$c" 'label'
body="$(body_of create)"
expect_has "unknown pin: names the skill" "$body" '### `playwright:playwright`'
expect_has "unknown pin: says what to run" "$body" 'Run `plugins/playwright/skills/playwright/scripts/update.sh`; restore or re-vendor what it names; its output is in the run'"'"'s job summary.'
Expand Down Expand Up @@ -556,20 +568,16 @@ GH_STUB_FAIL=reopen
run_sut "$DRIFT"
if [[ "$CODE" != 0 ]]; then pass "failed reopen: exits nonzero"; else bad "failed reopen: exits nonzero" "$OUT"; fi
c="$(calls)"
expect_has "failed reopen: the closed issue keeps the label added first" "$c" 'issue edit 12 --add-label needs-human'
expect_lacks "failed reopen: does not edit the closed issue's body" "$c" 'issue edit 12 --body-file'
# A failed label add stops that issue's reopen; the next upstream still runs.
# A failed reopen stops that issue's body edit; the next upstream still runs.
TWO_DRIFT="$TMP/two-drift.txt"
printf '%s\n' \
"page repo=acme/widgets pin=$PIN head=$HEAD status=drift path=docs/upstream/widgets.md" \
"row line=7 status=M path=skills/alpha/SKILL.md" \
"page repo=other/tools pin=$PIN head=$HEAD status=drift path=docs/upstream/tools.md" >"$TWO_DRIFT"
GH_STUB_FAIL=edit
run_sut "$TWO_DRIFT"
if [[ "$CODE" != 0 ]]; then pass "failed label add: exits nonzero"; else bad "failed label add: exits nonzero" "$OUT"; fi
c="$(calls)"
expect_lacks "failed label add: no reopen" "$c" 'issue reopen'
expect_has "failed label add: the next upstream still runs" "$c" 'issue create --title Upstream drift: other/tools'
if [[ "$CODE" != 0 ]]; then pass "failed reopen, two upstreams: exits nonzero"; else bad "failed reopen, two upstreams: exits nonzero" "$OUT"; fi
expect_has "failed reopen: the next upstream still runs" "$(calls)" 'issue create --title Upstream drift: other/tools'
GH_STUB_FAIL=""

# --- untrusted text never reaches shell evaluation (bash 5.1 semantics) -----
Expand Down
Loading