docs(adr): add ADR 0080 and 0081 for config.yaml vs. agent env scope

[ralphbean]

Summary

• Adds ADR 0080, amending ADR 0049: a knob that's pipeline/dispatch policy or applies uniformly across agents is a config.yaml field (never also an env var); a knob that tunes one specific agent's own behavior is an {AGENT}_-prefixed env var in that agent's env.runner/env.sandbox (never a config.yaml field).
• Resolves the ambiguity raised in fullsend-ai/agents#567 (review comment): TRIAGE_AUTO_CODE correctly stays a harness env var (called out as a boundary case), and the per-repo/org override path is documenting the existing harness composition mechanism, not adding a config.yaml field.
• Adds ADR 0081, amending ADR 0049 and laterally related to ADR 0080: reserves the CI workflow env: block for infrastructure plumbing and CI-runtime-only values, never static agent behavior defaults. Split out during review after finding agents#567's docs already drifting toward workflow-env overrides for behavior knobs.
• Cross-references added between ADR 0049, ADR 0080, ADR 0081, and docs/architecture.md.
• Swapped auto_merge for kill_switch as ADR 0080's config.yaml example — auto_merge turned out to be dead code (parsed but never consumed), tracked separately in internal/config: defaults.auto_merge is parsed but never consumed #5808.

Test plan

• make lint passes (ADR status/number/frontmatter checks)
• Verify docs render correctly on GitHub

Assisted-by: Claude Opus 4.6 noreply@anthropic.com

[qodo-code-review]

PR Summary by Qodo

docs: Add ADR 0080 clarifying config.yaml vs agent env var scope

📝 Documentation 🕐 10-20 Minutes

AI Description

• Add ADR 0080 defining when a knob is a config.yaml field vs an {AGENT}_ env var.
• Cross-link ADR 0080 from ADR 0049 to complete the env-var convention guidance.
• Update architecture docs with the same config-surface boundary rule for consistency.

Diagram

graph TD
ADR80["ADR 0080"] --> ADR49["ADR 0049"] --> EnvRule["{AGENT}_ env var rule"]
ADR80 --> ArchDoc["docs/architecture.md"] --> Boundary["Config surface boundary"]
Boundary --> ConfigYaml["config.yaml fields"] --> CrossAgent["Cross-agent / policy"]
Boundary --> HarnessEnv["Harness env vars"] --> SingleAgent["Single-agent behavior"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Fold the scope rule into ADR 0049 only

• ➕ Fewer ADRs to navigate
• ➕ Single doc for env-var guidance
• ➖ Mixes two distinct decisions (naming vs placement) in one ADR
• ➖ Harder to reference placement guidance independently from naming convention

2. Add a non-ADR conventions page instead of a new ADR

• ➕ Potentially more discoverable for day-to-day contributors
• ➕ Can evolve without ADR ceremony
• ➖ Weaker governance/traceability for a cross-cutting configuration rule
• ➖ Doesn’t clearly ‘amend’ ADR 0049 or fit the existing decision record structure

Recommendation: Keep ADR 0080 as a separate, explicit amendment to ADR 0049. The placement rule is a distinct architectural convention (config surface boundaries) that benefits from ADR-level traceability, and the cross-links added here make the guidance discoverable from both the env-var convention (ADR 0049) and the system overview (docs/architecture.md).

Files changed (3) +88 / -0

Documentation (3) +88 / -0

0049-agent-configuration-env-var-convention.mdLink ADR 0049 to ADR 0080 for config-surface placement +5/-0

Link ADR 0049 to ADR 0080 for config-surface placement

• Adds a clarifying note that ADR 0049 only covers naming/delivery for agent-specific knobs. Points readers to ADR 0080 for the rule deciding env var vs config.yaml placement.

docs/ADRs/0049-agent-configuration-env-var-convention.md

0080-config-yaml-vs-agent-env-var-scope.mdAdd ADR 0080 defining config.yaml vs agent env var scope +78/-0

Add ADR 0080 defining config.yaml vs agent env var scope

• Introduces a new ADR that mandates each configuration knob lives in exactly one surface. Defines the decision boundary (cross-agent/policy -> config.yaml; single-agent behavior -> {AGENT}_ env vars) and applies it to TRIAGE_AUTO_CODE.

docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md

architecture.mdDocument the config-surface boundary and reference ADR 0080 +5/-0

Document the config-surface boundary and reference ADR 0080

• Adds a short architecture-level bullet describing when a knob is a harness env var versus a config.yaml field. Links to ADR 0080 to make the rule discoverable from the system overview.

docs/architecture.md

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 2:04 PM UTC · Ended 2:05 PM UTC
Commit: 8a964d3 · View workflow run →

[github-actions]

Site preview

Preview: https://d5982529-site.fullsend-ai.workers.dev

Commit: 30c7d8021465d37673e24d1d677c402dcea46c89

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. ADR 0080 Context missing links ✓ Resolved 📜 Skill insight ⚙ Maintainability

Description

In docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md, the ## Context section references `ADR
0049` but does not link to it, and it provides no links to the relevant problem docs (e.g.,
agent-infrastructure, governance) to anchor the context. This reduces traceability and violates
the ADR requirements for contextual cross-references.

Code

docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md[R23-36]

+## Context
+
+[fullsend-ai/agents#567](https://github.com/fullsend-ai/agents/pull/567)
+added `TRIAGE_AUTO_CODE` as a harness `env.runner` default in
+`harness/triage.yaml`. A reviewer flagged that fullsend-ai/fullsend#1754,
+the issue that requested the knob, asked for it to "live in the per-repo/
+per-org config surface" — i.e. `.fullsend/config.yaml` — not a harness
+default (see the [review
+discussion](https://github.com/fullsend-ai/agents/pull/567#discussion_r3686020058)).
+`config.yaml` already carries fields like `create_issues.allow_targets`
+that are unrelated to any single agent. ADR 0049 defines how agent config
+env vars are *named* (`{AGENT}_{SETTING_NAME}`) but says nothing about
+*when* a knob should be a `config.yaml` field instead of an env var, so
+there was no rule to check the PR against.

Relevance

●●● Strong

Team often accepts ADR cross-reference/link fixes (accepted in #1549; similar Context link request
partially accepted in #2663).

PR-#1549
PR-#2663
PR-#80

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Rule 1062094 requires an explicit link to related ADRs within the ## Context section; ADR 0080’s
context mentions ADR 0049 without linking it there. Rule 1062093 requires the Context to link to
relevant problem docs; ADR 0080’s Context contains no links to files under docs/problems/ despite
relates_to indicating applicable problem areas.

docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md[23-36]
Skill: writing-adrs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The `## Context` section in ADR 0080 lacks required cross-reference links: it mentions `ADR 0049` without a link in the Context section, and it doesn’t link to the relevant problem docs to ground the context.

## Issue Context
Compliance requires ADR Context sections to (1) cross-reference related ADRs via explicit links when they are referenced/related, and (2) link to problem docs rather than relying on inline narrative alone.

## Fix Focus Areas
- docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md[23-36]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 2:06 PM UTC · Ended 2:11 PM UTC
Commit: e94e2e6 · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 2:13 PM UTC · Ended 2:25 PM UTC
Commit: eb2c2d9 · View workflow run →

[ben-alkov]

LGTM

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 2:27 PM UTC · Ended 2:27 PM UTC
Commit: f17576c · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 2:28 PM UTC · Completed 2:41 PM UTC
Commit: 9dcdffe · View workflow run →

[fullsend-ai-review]

Review

Findings

Low

• [internal consistency] docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md:46 — The phrasing "This narrows ADR 0049's per-agent-vars rule" is imprecise — ADR 0049 was silent on the uniform-across-agents case (it only addressed independently-tunable settings). ADR 0080 is filling a gap rather than narrowing an existing rule. The distinction is correctly articulated in the same paragraph; this is a wording precision issue, not a logic error.

Previous run

Review

Findings

Low

• [internal consistency] docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md:46 — The phrasing "This narrows ADR 0049's per-agent-vars rule" is imprecise — ADR 0049 was silent on the uniform-across-agents case (it only addressed independently-tunable settings). ADR 0080 is filling a gap rather than narrowing an existing rule. The distinction is correctly articulated in the same paragraph; this is a wording precision issue, not a logic error.

Previous run (2)

Review

Findings

Low

• [internal consistency] docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md:46 — The phrasing “This narrows ADR 0049’s per-agent-vars rule” is imprecise — ADR 0049 was silent on the uniform-across-agents case (it only addressed independently-tunable settings). ADR 0080 is filling a gap rather than narrowing an existing rule. The distinction is correctly articulated in the same paragraph; this is a wording precision issue, not a logic error.

Previous run (3)

Review

Findings

High

• [contradicts-new-decision] docs/agents/review.md:86 — The review agent documentation instructs users to "Set this in the CI workflow env: block" for REVIEW_FINDING_SEVERITY_THRESHOLD, a static agent behavior default. ADR 0081 (introduced in this PR) reserves CI workflow env: injection for infrastructure plumbing (credentials, project IDs, regions) and CI-runtime-only computed values — not static agent behavior defaults. ADR 0055's canonical example already sets REVIEW_FINDING_SEVERITY_THRESHOLD in the harness's env.sandbox, consistent with ADR 0081's rule. Merging the ADR without updating this guidance would leave user-facing documentation directing readers to use the exact pattern the ADR says to avoid.
  Remediation: Update the guidance at line 86 to recommend harness composition (base: override of the upstream harness) for per-repo/per-org customization of REVIEW_FINDING_SEVERITY_THRESHOLD, and cross-reference ADR 0081 for the rationale.

Low

• [missing-cross-reference] docs/ADRs/0024-harness-definitions.md:29 — ADR 0024 describes required_env as values "provided by the CI workflow at runtime from org secrets and event context" (lines 70–74) without noting that ADR 0081 has narrowed CI workflow env injection scope. The existing description focuses on the mechanical delivery path and is not actively misleading, but a cross-reference annotation would improve discoverability.
  Remediation: Consider adding an amendment annotation referencing ADR 0081, similar to the annotations this PR adds to ADR 0049 and ADR 0055.

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

Previous run (4)

Review

Findings

Low

• [Technical documentation accuracy] docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md:67 — The parenthetical reference (see [ADR 0055](0055-unified-env-var-delivery.md), § Runner-side expansion) cites a section heading that does not exist in ADR 0055. The actual section heading describing os.Expand behavior is ### Runner behavior. A reader following this cross-reference would not find the cited section.
  Remediation: Change § Runner-side expansion to § Runner behavior to match the actual heading in ADR 0055.

Previous run (5)

Review

Findings

Medium

• [Technical documentation accuracy] docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md:67 — The ADR states that shell-style passthrough expressions like ${TRIAGE_AUTO_CODE:-on} in env.runner/env.sandbox "would not expand and instead be treated as a literal value." This is incorrect. Go's os.Expand (used at internal/cli/run.go:538-541) parses ${...} and extracts the entire content between the braces as the variable name. For ${TRIAGE_AUTO_CODE:-on}, it calls the expander with key TRIAGE_AUTO_CODE:-on, which os.Getenv resolves to an empty string — not the literal ${TRIAGE_AUTO_CODE:-on}. The actual failure mode is silent expansion to an empty string (data loss), which is worse than literal preservation. The conclusion that passthrough syntax should not be used is correct, but the stated failure mode is wrong. ADR 0055 already correctly documents this at line 121-123: "os.Expand supports $VAR and ${VAR} syntax only — no default values."
  Remediation: Change "so passthrough syntax would not expand and instead be treated as a literal value" to something like "so passthrough syntax would be mis-parsed — os.Expand treats the entire VAR:-default as the variable name, which resolves to an empty string rather than applying the intended default."

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

Previous run (6)

Looks good to me

Previous run (7)

Review

Findings

Low

• [cross-reference-placement] docs/ADRs/0049-agent-configuration-env-var-convention.md:22 — The annotation uses "Clarified by" while the existing codebase uses "Amended by" or "Extended by" for post-acceptance ADR annotations (e.g., ADR 0024 line 23, ADR 0038 line 25). Additionally, ADR 0080 itself declares "Amends: [ADR 0049]" in its header, creating a mismatch: the amending ADR says "Amends" but the amended ADR says "Clarified by" rather than "Amended by". Consider using "Amended by [ADR 0080]..." for consistency.

• [docs-currency] docs/ADRs/0055-unified-env-var-delivery.md:17 — ADR 0055 amends ADR 0049 and discusses the {AGENT}_ env var naming convention but does not reference ADR 0080, which now clarifies when a knob should use the {AGENT}_ env var pattern versus being a config.yaml field. A "See also" cross-reference near line 181 (where ADR 0055 states "ADR 0049's env var naming convention applies unchanged") would improve discoverability.

---

Labels: PR adds a new ADR and updates documentation files only (ADRs, architecture.md, user guide)

[ralphbean]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 2:48 PM UTC · Completed 2:55 PM UTC
Commit: 9dcdffe · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:15 PM UTC · Completed 3:31 PM UTC
Commit: afc0e1a · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:21 PM UTC · Completed 4:35 PM UTC
Commit: 30c7d80 · View workflow run →

[waynesun09]

Approving after a full convention pass on both ADRs at head (30c7d80) plus verification of the round-2/3 fix claims against main:

• host variable … is not set fail-fast wording matches internal/harness/harness.go:591 — the afc0e1a failure-mode correction is accurate.
• ADR 0081's CODE_ALLOWED_TARGET_BRANCHES consequence checks out: ADR 0053's migration section and Consequences do place it in harness runner_env, not workflow YAML, so pre-existing-non-conformance framing (rather than a new exception category) is right.
• The ADR 0055 citation now points at a real heading (§ Runner behavior).
• No 0080/0081 numbering collisions on current main; architecture.md and the 0049 annotation are in the diff.
• One-decision rule holds for both — the 0081 split was the right resolution of the earlier scope finding.

All of my earlier findings are addressed. Two non-blocking notes: ADR 0080 is ~107 content lines against the <80 target — review-driven additions account for the growth and each carries decision-relevant content, but the passthrough-syntax mechanics in the override paragraph could compress to a sentence plus the ADR 0055 link if you want it shorter; and the open fullsend-ai-review [low] on the "narrows" phrasing re-litigates the settled per-agent-vars thread — fine to resolve as-is.

From slack: lgtm, added a small comment here: https://github.com/fullsend-ai/fullsend/pull/5798/changes#r3705550910

[ralphbean]

Thanks @maruiz93 , @waynesun09 !

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 5:37 PM UTC · Completed 6:04 PM UTC
Commit: 30c7d80 · View workflow run →

[fullsend-ai-retro]

Retro: PR #5798 — ADR 0080/0081 for config.yaml vs. agent env scope

Workflow shape: 12 commits (7 human, 5 bot) · 11 review runs (3 cancelled, 8 successful) · 3 fix runs · 3 human reviewers · merged in ~3 days

Overall assessment: The workflow produced a high-quality outcome — two well-scoped ADRs with thorough human review that caught design-level issues and technical inaccuracies. The review bot added value on cross-reference consistency and naming conventions. However, two systemic issues consumed extra iterations and human attention.

Key findings

1. Review bot asserted incorrect code behavior; challenger confirmed the same error (evidence for agents#420, agents#549)

The correctness sub-agent correctly identified that the ADR's stated passthrough failure mode was wrong ("treated as a literal value"). However, its own correction — that os.Expand silently resolves ${TRIAGE_AUTO_CODE:-on} to an empty string — was also technically incorrect. The actual behavior is that ValidateRunnerEnvWith (at internal/harness/harness.go:586) runs before os.Expand and fail-fasts with a clear error message. Both the correctness sub-agent and the challenger read run.go and saw the ValidateRunnerEnvWith call on-screen (lines 527-529) but focused exclusively on os.Expand (lines 531-542) without tracing the validation function. The challenger even wrote a standalone Go program — but tested os.Expand in isolation rather than the actual code path. waynesun09 caught this by tracing through both functions and replicating the validation logic. This added at least one unnecessary fix iteration.

2. Review bot re-litigated the settled "narrows" wording 3 times (evidence for #1013, #5265, #1672)

The word "narrows" in ADR 0080 was the deliberate outcome of a human review discussion between waynesun09 and ralphbean. The review bot then raised a [low] finding claiming the wording was imprecise — repeated identically across 3 review runs (on commits a7b458, afc0e1a, and 30c7d80). waynesun09's final approval explicitly dismissed it as "re-litigat[ing] the settled per-agent-vars thread." This is the same pattern documented in #5760 (54 comments on a 78-line file across 6 runs) and #5265 (re-review anchoring should incorporate author response context).

3. Fix agent accepted incorrect technical claim without independent verification (evidence for agents#420)

The fix agent took the review bot's incorrect os.Expand assertion at face value in both fix iteration 2 (commit d6fced4) and iteration 3 (commit a7b458). Neither fix run independently verified the claim against the actual code path. This matches the pattern in agents#420 where the fix agent implemented changes based on a false assertion about JSON Schema validation.

4. Autonomy readiness: human review was essential for design-level quality

Human reviewers caught all design-level issues: ADR 0049 contradiction (waynesun09), override convention needing its own ADR (maruiz93 → led to ADR 0081 split), TRIAGE_AUTO_CODE classification being asserted rather than derived (waynesun09), and cross-repo consistency with agents#567 (waynesun09). The review bot's value was concentrated on formatting/consistency (wrong verb, missing cross-refs, wrong section heading). For ADR/design-doc PRs, the current autonomy level is appropriate — the bot catches mechanical issues while humans handle architectural reasoning.

Proposal filed

1 proposal targeting fullsend-ai/agents — challenger sub-agent should trace surrounding control flow when verifying technical assertions, not just the cited lines.

No proposal filed (covered by existing issues)

• Finding dedup across iterations: #1013, #2816, #5007
• Re-litigation of settled points: #1672, #5265
• Fix agent blindly accepting review findings: agents#420, agents#549

Proposals filed

• Challenger sub-agent should trace control flow around cited lines, not just verify cited code (in fullsend-ai/agents)