[justinmclean]

Summary

• Every batch (sweep) skill documents "stop and surface" for any per-item error, so one bad issue sinks a whole sweep and a forge outage reads as a failure of every item it touched.
• This PR proposes, as a proposed spec plus two plan items, a two-step fix: a per-item failure budget on the read/classify phase (the write phase keeps stop-and-surface so a retried post can never double-comment), and a harness-outage exclusion that classifies 429 / 5xx / reset / timeout / auth-expiry failures separately, retries once, and trips a breaker that reports an outage with no item marked failed.
• The two steps are proposed together because the exclusion is meaningless without the budget. No skill, tool or eval changes here.

Type of change

• Documentation (docs/, README.md, CONTRIBUTING.md)
• Other: spec-loop spec and implementation plan

Test plan

• uv run --project tools/spec-validator spec-validate tools/spec-loop/specs/ passes with the new spec
• python3 tools/dev/check-doc-sync.py passes (spec indexed in specs/README.md and specs/overview.md)
• prek run --files <changed files> passes (markdownlint, typos, lychee, spec-validate, check-doc-sync)

RFC-AI-0004 compliance

• HITL — the proposal keeps every write gated and explicitly rules out retrying writes
• Conversational + correctable — budget and breaker are proposed as adopter-tunable config keys with template defaults

Linked issues

None yet; the plan items batch-failure-budget and harness-outage-exclusion (blocked on the first) track the implementation.

Notes for reviewers (optional)

• The failure classifier (which status codes mean "outage" on GitHub, GitLab, Forgejo, Jira, Bitbucket) is left to the tracker capability contract so each adapter maps its own; the spec does not pin per-adapter tables.
• Later plan items were renumbered (5 to 9) and their cross-references updated.
• Generative-AI disclosure: authored with Claude Code (Fable 5.1) under maintainer direction; commits carry the Generated-by: trailer.

[potiuk]

I rebased this branch onto main (90c77c4 → 71999df) to clear the conflict in IMPLEMENTATION_PLAN.md: main had replaced the plan's work-item list, so I kept main's list and appended your two items as 7 and 8 (batch-failure-budget, then harness-outage-exclusion, blocked on 7), dropping the renumbering of items that no longer exist. Please pull before pushing again. The proposal itself reads well; splitting the budget (read phase) from the never-retried write phase is the right line. Two points below, the first applying to your other open PRs too.

Agents are assistants, not authors (tools/spec-loop/specs/batch-failure-budget.md)

MUST NOT use Co-Authored-By: with an AI agent as co-author. Agents are assistants, not authors — attributing them as authors misrepresents contribution and is contrary to ASF policy on AI-assisted contributions.

The commit on this branch is authored as Claude <noreply@anthropic.com>; the Generated-by: trailer is right, but the author field makes the agent the author outright. It is the same on #1928, #1929 and #1931. When a PR is squash-merged, GitHub adds a Co-authored-by: trailer for every commit author other than the PR author, so the squash commit on main would carry Co-authored-by: Claude <noreply@anthropic.com>, which is the attribution this rule forbids (and which the commit-trailer guard cannot see, because the trailer is written by GitHub, not by a local git commit). None of the last 300 commits on main is authored that way.

Suggested fix: Reset the author on each commit to yourself, keeping the Generated-by: trailer: git rebase --exec 'git commit --amend --no-edit --reset-author' origin/main, then force-push; and set user.name / user.email in the environment the agent commits from so new commits are yours.

Smaller observations

• See inline comments on tools/spec-loop/specs/batch-failure-budget.md:126.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The findings
below are observations, not blockers; an Apache Magpie
maintainer — a real person — will take the next look at the
PR. If you think a finding is mis-applied, please reply on
the PR and a maintainer will weigh in.

More on how Apache Magpie handles maintainer review:
Contributing guide.

[justinmclean]

Thanks Jarek. On the author point: ASF policy doesn't forbid this. The generative tooling page (https://www.apache.org/legal/generative-tooling.html) recommends either "Generated-by: " or "Co-authored-by: " in the commit message. The no-Co-Authored-By rule is this repo's own convention in AGENTS.md, not ASF policy.

[potiuk]

Thanks — the 403 rule now reads exactly as suggested, so a 403 on one unreadable item can no longer trip the breaker as a false outage. I rebased the branch onto main and pushed one small fixup commit, 2ebe0dc (please pull before pushing again):

• tools/spec-loop/specs/batch-failure-budget.md: new acceptance criterion 6 pinning the rule (a 403 on one item while the auth check still passes is an item failure and does not advance the breaker); the later criteria are renumbered.
• tools/spec-loop/IMPLEMENTATION_PLAN.md item 8: the harness bucket now carries the same 403 rule, so the classifier is not coded from the plan alone with every 403 as harness.

The PR description's "later plan items were renumbered (5 to 9)" no longer matches the diff against current main (it only adds items 7 and 8); the squash message below drops it.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
Contributing guide.