docs(#4718): add ADR 0072 for the pre-script output protocol - #5016
Conversation
|
🤖 Finished Review · ✅ Success · Started 1:59 PM UTC · Completed 2:09 PM UTC |
PR Summary by QodoAdd ADR 0072 documenting pre-script skip signalling via output protocol
AI Description
Diagram
High-Level Assessment
Files changed (2)
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Code Review by Qodo
1. ADR 0072 lacks context links
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
|
Looks good to me Low
Previous runLooks good to me Low
Previous run (2)Looks good to me Low
Previous run (3)Looks good to me Previous run (4)Looks good to me Previous run (5)Review of #5016 — ADR 0072: pre-script skip-flag conventionVerdict: approve · 1 low finding SummaryClean docs-only ADR recording the What was checked
Prior review finding status
Findings1. Context section overstates which gated steps run before
|
| Dimension | Result |
|---|---|
| Correctness | ✅ Internal logic is consistent. The {AGENT}_SKIP_{THING} naming genuinely follows ADR 0049's {AGENT}_{SETTING_NAME} syntax. All referenced ADRs (0024, 0031, 0045, 0049) exist. The code/fix examples correctly illustrate the "whichever invocation the pipeline depends on keeps default behavior" principle. |
| Security | ✅ No findings — clean docs-only change. No secrets, injection vectors, or permission changes. |
| Intent & coherence | ✅ Traces to #4718. Scope matches: one new ADR + one architecture.md bullet. ADR number 0072 is correct (0069 is highest on main; 0070–0071 claimed by open PRs). Status is Accepted (correct for a new ADR per AGENTS.md). relates_to references valid problem docs. PR title follows COMMITS.md (docs type). |
| Style & conventions | ✅ Frontmatter structure, section ordering, and relative link format match recent peer ADRs (0067–0069). The architecture.md bullet matches surrounding formatting (no period before the ADR parenthetical, consistent with all other bullets in the section). |
| Docs currency | ✅ architecture.md updated in the correct section (Agent Harness > Decided). VitePress ADRs sidebar uses getMarkdownFiles() — auto-discovered, no config change needed. |
| Cross-repo contracts | ⏭ Skipped — no APIs, schemas, or exported interfaces modified. |
Findings
1. Missing ADR 0055 reference for env.runner delivery mechanism · low
File: docs/ADRs/0072-pre-script-skip-flag-convention.md (References section)
The References section credits ADR 0024 and ADR 0045 for "runner_env / env.runner delivery mechanism," but env.runner was introduced by ADR 0055 (which deprecated runner_env). ADR 0024 defines runner_env; ADR 0045 defines the forge-portable schema — neither defines env.runner.
The architecture.md bullet for ADR 0055 (lines 112–116) sits directly above the new ADR 0072 bullet, so readers navigating from architecture.md have the deprecation context. However, readers arriving at the ADR directly would benefit from the reference.
Suggested follow-up: Add [ADR 0055](0055-unified-env-var-delivery.md) to the References line, e.g.:
- [ADR 0024](...), [ADR 0045](...), [ADR 0055](...) — `runner_env` (deprecated) / `env.runner` delivery mechanism
This is not blocking — the surrounding context in architecture.md and ADR 0049 already clarifies the deprecation.
Reviewed: 2026-07-15 · Dimensions: correctness (opus), security (opus), intent (sonnet), style (sonnet), docs (sonnet) · Challenger pass: opus
Labels: PR adds a new ADR documenting a harness pre-script convention and updates docs/architecture.md
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
fullsend-ai-review
Bot
added
ready-for-merge
Two fixes from ADR review of #5016: - Cross-reference ADR 0055 (unified env var delivery, deprecates runner_env in favor of env.runner/env.sandbox) instead of naming runner_env and env.runner as interchangeable options with no guidance on which to prefer. - Correct a Consequences bullet that implied removing the inline call only needs fullsend run to surface pre-script outputs earlier — Context already establishes the steps it gates run in an earlier workflow step position, so that alone wouldn't be sufficient; actually reordering those steps would be required too. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
Two fixes from ADR review of #5016: - Cross-reference ADR 0055 (unified env var delivery, deprecates runner_env in favor of env.runner/env.sandbox) instead of naming runner_env and env.runner as interchangeable options with no guidance on which to prefer. - Correct a Consequences bullet that implied removing the inline call only needs fullsend run to surface pre-script outputs earlier — Context already establishes the steps it gates run in an earlier workflow step position, so that alone wouldn't be sufficient; actually reordering those steps would be required too. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
69151a9 to
92318d7
Compare
|
🤖 Review · ❌ Terminated · Started 9:40 PM UTC · Ended 9:50 PM UTC |
Site previewPreview: https://d435deff-site.fullsend-ai.workers.dev Commit: |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
fullsend-ai-review
Bot
added
ready-for-merge
Records the pattern introduced in #5013/fullsend-ai/agents#175 so the next agent that needs to gate expensive workflow setup behind a fast pre-check (per rh-hemartin's request for consistency across agents, one: an {AGENT}_SKIP_{THING} env var, set on whichever of the two pre-script call sites should skip the redundant/expensive part. Distinguishes this from ADR 0049's agent-configuration env vars — same {AGENT}_{SETTING} syntax, but an internal invocation-context signal rather than a user-facing behavioral knob, so it belongs in script/harness comments, not docs/agents/<agent>.md. Scopes the decision to agents that actually need workflow-level gating (code, fix today) rather than mandating it retroactively for agents that don't currently duplicate pre-script execution. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
Two fixes from ADR review of #5016: - Cross-reference ADR 0055 (unified env var delivery, deprecates runner_env in favor of env.runner/env.sandbox) instead of naming runner_env and env.runner as interchangeable options with no guidance on which to prefer. - Correct a Consequences bullet that implied removing the inline call only needs fullsend run to surface pre-script outputs earlier — Context already establishes the steps it gates run in an earlier workflow step position, so that alone wouldn't be sufficient; actually reordering those steps would be required too. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
The skip-flag convention this ADR originally recorded was withdrawn after review (#5013 and agents#175 closed as superseded). Rewrite the ADR — still unmerged, so immutability does not apply — to record the decision that replaced it: pre-scripts run exactly once, inside fullsend run, signalling skips via the pre-script output protocol shipped in #5737, with the field-level contract in docs/normative/prescript-output/v1. Addresses the review feedback on this PR: options are now one paragraph each with the decision and its reasons in the Decision section; the gating no longer lives in GH workflow YAML at all; and no variables pass between invocations, dissolving the portability concern rather than specifying a mechanism for it. The non-template References section is folded into inline links. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
waynesun09
changed the title
- Renumber to 0079 to avoid collision with PR fullsend-ai#2791 (ADR 0071 auto-merge) and PR fullsend-ai#5016 (ADR 0072 pre-script output protocol) - Replace deprecated runner_env with env.runner/env.sandbox per ADR 0055 - Remove incorrect ADR 0045 forge: citation for Jira-aware behavior - Narrow Consequences claim to Jira-token portion of ADR 0063's open question - Soften idempotent assertion to intended contract - Add missing ADR 0063 cross-reference in architecture.md Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>
Pre-scripts can no longer mint their own tokens since #5837 stripped the OIDC mint credentials from the pre-script environment (#5832, enforcing ADR 0073). Record it as a consequence annotation so the open forge-call ownership question reads as token possession, not minting capability. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
|
Added one consequence bullet (2e37656): since acceptance of this direction, #5837 (#5832) stripped the OIDC mint credentials from the pre-script environment, enforcing ADR 0073's harness-as-sole-minter intent at this boundary. Recorded as an annotation so the deliberately-open forge-call ownership bullet now reads as a question of token possession — scripts can no longer mint their own. No changes to Context/Options/Decision. |
|
🤖 Finished Review · ✅ Success · Started 1:59 PM UTC · Completed 2:14 PM UTC |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
ralphbean
left a comment
ralphbean
left a comment
There was a problem hiding this comment.
LGTM. One non-blocking note inline.
|
🤖 Finished Review · ✅ Success · Started 7:24 PM UTC · Completed 7:37 PM UTC |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
The frontmatter names agent-architecture and agent-infrastructure but the Context never linked either, so the connection wasn't visible from the text. Assisted-by: Claude Signed-off-by: Wayne Sun <gsun@redhat.com>
|
🤖 Finished Review · ✅ Success · Started 7:55 PM UTC · Completed 8:10 PM UTC |
|
🤖 Finished Retro · ✅ Success · Started 1:16 PM UTC · Completed 1:34 PM UTC |
Retro: PR #5016 — ADR 0072 (Pre-Script Output Protocol)TimelineThis was a human-authored ADR by waynesun09 that underwent a fundamental rewrite during review:
Review Agent Assessment7 review runs at What worked well:
Gaps:
Existing Issue EvidenceAll identified improvements are covered by open issues. New evidence from this PR:
Autonomy AssessmentThe review agent reliably verified documentation surface quality (factual accuracy, cross-references, style compliance). Post-rewrite approvals were correct. However, the pre-rewrite approvals were premature — the design was flawed in ways only human architectural judgment identified. Increased autonomy for ADR reviews is not warranted until the design-level review gap (fullsend#1469) is addressed. No New ProposalsNo new proposals filed — all improvement areas are well-covered by existing open issues referenced above. |
3 participants
Summary
Records the
{AGENT}_SKIP_{THING}skip-flag convention introduced by #5013 / fullsend-ai/agents#175, so it's a documented pattern rather than something reviewed from scratch each time an agent needs it.Related Issue
Relates to #4718 — specifically rh-hemartin's request that every agent gate expensive setup consistently, not just code/fix.
Why now
rh-hemartin pushed back on the env-var mechanism in #4762 before agreeing it was the right approach, and separately asked for it to be applied consistently across agents. Rather than re-litigate the mechanism on every future PR that needs it, this ADR records the decision once: what the flag naming is, which invocation sets it, why it's a different category from ADR 0049's user-facing config vars, and the scope (apply when an agent actually needs workflow-level gating — not retroactively to agents that don't).
Changes
docs/ADRs/0072-pre-script-skip-flag-convention.md— new ADR (Accepted)docs/architecture.md— one-bullet addition under "Agent Harness > Decided:", linking the new ADR (perskills/writing-adrs/SKILL.md's living-document update step)Testing
make lintpasses (staged), includinglint ADR statuses,lint ADR numbers,lint ADR frontmatter,lint markdown linksskills/writing-adrs/SKILL.mdchecklist: scanneddocs/ADRs/onmain+ open PRs for in-flight numbers (0070 and 0071 both already claimed by other open PRs — used 0072), used the template, matched frontmatterstatusto the## Statusheading, no leading zeros in the title number