docs!: add ADR 0088 for CEL-guarded overlays in the harness schema

[ralphbean]

Summary

• Rewrites ADR 0088 to adopt the overlays: approach proposed by @ifireball in the first review, replacing the original tracker/forge split direction.
• Adds an overlays: list field to the harness schema — each entry has a CEL when: expression and the same override fields as ForgeConfig. Multiple matching entries are merged in declaration order using ADR-0045 merge semantics.
• Deprecates forge: (remains functional, Lint() warns) in favor of overlays:, which can condition on any event property rather than only the forge platform.
• Updates docs/architecture.md with the corresponding Decided entry.

Direction change after v1 review

The original PR proposed a tracker: block sibling to forge:, keyed by platform. @ifireball's review pointed out that picking and choosing conditioning axes ends up feeling arbitrary, and proposed generalizing to CEL-guarded conditional sections instead. This rewrite adopts that direction — overlays: replaces both the tracker: proposal and (eventually) forge: itself.

Test plan

• make lint passes (ADR frontmatter/status/number/link linters)

🤖 Generated with Claude Code

[qodo-code-review]

PR Summary by Qodo

Add ADR 0088 for tracker/forge harness config split

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Document decision to add tracker: alongside forge: in harness schema.
• Specify shared validation/resolution/merge behavior and explicit precedence rules.
• Capture motivation and rollout implications for Jira-triggered code-agent runs.

Diagram

graph TD
  ADR["ADR 0088"] --> Harness["Harness schema"] --> Forge["forge:<platform>"] --> Merge["Shared resolve/merge"]
  Harness --> Tracker["tracker:<platform>"] --> Merge --> Env["FULLSEND_FORGE / FULLSEND_TRACKER"]
  Env --> Runtime["Runner & sandbox"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep a single `forge:` axis and add `jira` as a forge platform

• ➕ Minimal schema surface change (no new top-level key).
• ➕ Avoids introducing two platform variables (FULLSEND_FORGE and FULLSEND_TRACKER).
• ➖ Semantically incorrect (Jira is not a forge/client for repo operations).
• ➖ Cannot express “read from tracker X, write to forge Y” cleanly in one harness.

2. Add separate scalar fields (e.g., `tracker_platform`, `forge_platform`) without per-platform blocks

• ➕ Very simple config surface for selecting platforms.
• ➕ Avoids duplicating script/env/skills blocks per platform.
• ➖ Loses the ADR-0045 pattern of per-platform overrides (pre_script, runner_env, etc.).
• ➖ Makes composition/merging across base: less powerful and harder to evolve.

Recommendation: Proceed with the documented tracker: sibling block approach. It cleanly separates the two concerns (issue source vs code host target), preserves ADR-0045’s per-platform override and composition model via shared merge/resolution logic, and makes precedence rules explicit for the few scalar fields that can conflict.

Files changed (1) +160 / -0

Documentation (1) +160 / -0

0088-tracker-harness-config-split.mdAdd ADR defining 'tracker:'/'forge:' split and precedence rules +160/-0

Add ADR defining 'tracker:'/'forge:' split and precedence rules

• Introduces ADR 0088 documenting a new 'tracker:' harness section alongside 'forge:', including validation/resolution generalization, 'base:' composition behavior, and explicit scalar precedence (forge resolves before tracker, tracker wins). Captures runtime expectations around 'FULLSEND_TRACKER' derivation and backward compatibility implications.

docs/ADRs/0088-tracker-harness-config-split.md

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 5:49 PM UTC · Completed 6:04 PM UTC

Commit: bfa8bf3 · View workflow run →

[github-actions]

Site preview

Preview: https://66ff47b4-site.fullsend-ai.workers.dev

Commit: f16b496f0dc357fa0b9a9815274322abaa6a72ac

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Code Review by Qodo

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

1. docs/architecture.md missing ADR 0088 ✓ Resolved 📜 Skill insight ⚙ Maintainability

Description

This PR adds a new ADR with status: Accepted, but docs/architecture.md is not updated to include
a corresponding "Decided:" note linking to ADR 0088. This leaves the architecture overview stale
relative to the newly accepted decision.

Code

docs/ADRs/0088-tracker-harness-config-split.md[R2-4]

+title: "88. Tracker/forge split in the harness config schema"
+status: Accepted
+relates_to:

Relevance

●●● Strong

Architecture.md “Decided” bullets are actively maintained; teams accept keeping overview in sync
with ADRs.

PR-#2743
PR-#1578

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062100 requires an architecture.md update when an ADR is accepted. The new ADR
explicitly sets status: Accepted, but docs/architecture.md’s harness "Decided:" list does not
include a link/reference to ADR 0088.

docs/ADRs/0088-tracker-harness-config-split.md[1-22]
docs/architecture.md[87-116]
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
A newly accepted ADR must be accompanied by a `docs/architecture.md` update that links to the ADR under an appropriate "Decided:" subsection. ADR 0088 is accepted, but architecture.md doesn’t reference it.

## Issue Context
`docs/architecture.md` already has an "Agent Harness" section with a "Decided:" list that references related harness ADRs (e.g., ADR 0045) but not ADR 0088.

## Fix Focus Areas
- docs/ADRs/0088-tracker-harness-config-split.md[1-22]
- docs/architecture.md[87-116]

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

---

2. ADR 0088 has multiple decisions ✗ Dismissed 📜 Skill insight ⚙ Maintainability

Description

The ## Decision section bundles multiple distinct decisions (type rename, schema extension with
tracker:, precedence rules, and runtime platform selection) rather than recording exactly one
decision. This makes the ADR harder to audit/supersede cleanly and violates the ADR single-decision
requirement.

Code

docs/ADRs/0088-tracker-harness-config-split.md[R51-54]

+This is scoped to `internal/harness`; it is unrelated to and does not touch
+`internal/repos.ForgeConfig`, a separate type for admin-manifest CI paths.
+
+Add a `Tracker map[string]*PlatformConfig` field to the `Harness` struct,

Relevance

●● Moderate

No clear precedent enforcing “single-decision ADR”; may be seen as acceptable grouping for one
feature area.

PR-#5916

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062089 requires that each ADR record exactly one decision. In ADR 0088, the
Decision section includes multiple separate decisions (rename ForgeConfig → PlatformConfig, add
a new tracker: map, define precedence/runtime selection rules), which exceeds a single decision
record.

docs/ADRs/0088-tracker-harness-config-split.md[45-98]
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
ADR 0088’s `## Decision` section contains multiple distinct decisions (e.g., Go type rename, adding `tracker:` to schema, precedence rules, runtime fallback rules). The compliance requirement is that each ADR records exactly one decision.

## Issue Context
This ADR is being added as `Accepted`, so it should be a crisp, single decision record. If multiple sub-decisions are needed, either narrow this ADR to one decision and move the rest to separate ADRs, or restructure so only one decision remains and the rest become consequences/notes.

## Fix Focus Areas
- docs/ADRs/0088-tracker-harness-config-split.md[45-98]

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

---

3. Consequences bullets exceed 5 ✗ Dismissed 📜 Skill insight ⚙ Maintainability

Description

The ## Consequences section has 6 bullet points, and at least one bullet is more than one
sentence. This violates the required 3–5 one-sentence bullets format.

Code

docs/ADRs/0088-tracker-harness-config-split.md[R129-132]

+  the triggering issue) alongside `forge.github` (how to open the resulting
+  PR) in one file — the two resolve independently against their own
+  platform values, with no `forge.jira` entry required or possible.
+- Issue-tracking-only harnesses (e.g. triage) can also adopt `tracker:`

Relevance

●● Moderate

Consequences formatting rules seem inconsistently enforced; no close precedent on
bullet-count/one-sentence constraint.

PR-#5244

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062091 requires Consequences to be 3–5 one-sentence bullets. The Consequences
section in ADR 0088 contains 6 bullets, and the final bullet spans multiple sentences/lines.

docs/ADRs/0088-tracker-harness-config-split.md[126-160]
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
ADR Consequences must be 3–5 bullet points, each a single sentence. ADR 0088 has 6 bullets and includes multi-sentence content.

## Issue Context
The consequences list starts at `## Consequences` and runs through the end of the file.

## Fix Focus Areas
- docs/ADRs/0088-tracker-harness-config-split.md[126-160]

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

---

4. ADR exceeds 100 lines 📜 Skill insight ⚙ Maintainability

Description

ADR 0088’s body content (excluding frontmatter) is ~146 lines, exceeding the 100-line maximum. This
suggests the ADR is carrying too much detail and should be shortened or split.

Code

docs/ADRs/0088-tracker-harness-config-split.md[R158-160]

+  `tracker.jira` harness block and a `FULLSEND_TRACKER` derived from the
+  dispatch record's `source.system` are the pieces those issues need to
+  close.

Relevance

● Weak

Close rejection precedent: requests to cut ADRs to ≤100 lines were rejected previously.

PR-#2582

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062092 sets a 100-line maximum for ADR content excluding frontmatter. This ADR
runs to line 160 total, with the body starting at line 15, so the body is ~146 lines (>100).

docs/ADRs/0088-tracker-harness-config-split.md[15-160]
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
ADR content (excluding frontmatter) must not exceed 100 lines. ADR 0088 is substantially longer.

## Issue Context
The ADR includes extensive runtime/precedence explanation that may belong in architecture docs or a linked normative/spec document, or split across multiple ADRs.

## Fix Focus Areas
- docs/ADRs/0088-tracker-harness-config-split.md[15-160]

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

---

Context

✅ Compliance rules (platform): 54 rules

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

Tip of the day

💡 Did you know, you can keep summaries lean with Finding overflow, which tucks the rest behind 'View more'

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[fullsend-ai-review]

Review

Findings

Medium

• [algorithm-logic-consistency] docs/ADRs/0088-cel-guarded-overlays.md:162 — The base composition section contains an internal contradiction about overlay ordering. It states that mergeBaseIntoChild concatenates overlays lists with 'base entries first, child entries appended' then claims 'a child entry that matches shadows all base entries.' Under first-match-wins semantics, if base entries appear first, a matching base entry is selected before any child entry is reached — the base shadows the child, not the other way around. The sentence 'more-specific child when expressions can be ordered before base fallbacks by the harness author' is also incorrect — the harness author cannot control the concatenation order produced by mergeBaseIntoChild.
  Remediation: Either (a) reverse the concatenation order to child-first, base-appended (giving child entries priority under first-match-wins), or (b) keep base-first concatenation and update the prose to state that base entries take priority and child entries serve as fallbacks.

Low

• [adr-numbering-collision-risk] docs/ADRs/0088-cel-guarded-overlays.md — ADR 0088 skips from 0083 (latest on main). An open PR claims ADR 0086. No ADRs 0084, 0085, or 0087 exist on main or in visible open PRs. Verify no concurrent PRs have claimed these numbers before merging. The /renumber-adr skill can resolve any collision.
• [missing-deprecation-notice] docs/ADRs/0045-forge-portable-harness-schema.md — ADR 0045 introduced the forge: block for platform-specific overrides. ADR 0088 deprecates forge: in favor of the more general overlays: field, but ADR 0045's status remains 'Accepted' without noting the partial deprecation. Adding a cross-reference annotation (not a status change) would help readers discover the deprecation when reading the original ADR.
• [stale-doc] docs/contributing/harness-composition.md — The ADR's Consequences section notes that harness-composition.md will need updates for validateOverlays, ResolveOverlays, and overlays concatenation in mergeBaseIntoChild. Currently a follow-up item for when the implementation ships — no code changes are in this PR and forge merge functions are still correct.
• [stale-doc] docs/guides/user/bring-your-own-agent.md — The 'Forge-specific overrides' section presents forge: as the current syntax for platform-specific configuration. Once the overlays: implementation ships, this section will need a deprecation notice and cross-reference to ADR 0088. Currently a follow-up item since forge: remains the only working mechanism.

---

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

Review

Findings

Low

• [adr-numbering-collision-risk] docs/ADRs/0088-cel-guarded-overlays.md — ADR 0088 skips from 0083 (latest on main). An open PR claims ADR 0086. No ADRs 0084, 0085, or 0087 exist on main or in visible open PRs. Verify no concurrent PRs have claimed these numbers before merging. The /renumber-adr skill can resolve any collision.
• [missing-deprecation-notice] docs/ADRs/0045-forge-portable-harness-schema.md — ADR 0045 introduced the forge: block for platform-specific overrides. ADR 0088 deprecates forge: in favor of the more general overlays: field, but ADR 0045's status remains 'Accepted' without noting the partial deprecation. Adding a cross-reference annotation (not a status change) would help readers discover the deprecation when reading the original ADR.

Previous run (2)

Review

Findings

High

• [logic-error] docs/architecture.md:164 — The ADR 0088 link points to ADRs/0088-tracker-harness-config-split.md, but the actual file added by this PR is ADRs/0088-cel-guarded-overlays.md. This is a stale artifact from an earlier draft title and will be a broken link on merge.
  Remediation: Change the link target to ADRs/0088-cel-guarded-overlays.md.

Medium

• [logic-error] docs/ADRs/0088-cel-guarded-overlays.md:163 — The deprecation section claims forge: github: is equivalent to overlays: - when: event.source.system == "github", but these test different things. forge: is keyed by the forge platform (determined by detectForgePlatform() from the CI environment or --forge flag), while event.source.system identifies the event origin. A JIRA issue triggering an agent on GitHub Actions has forgePlatform="github" but event.source.system="jira", so the claimed mechanical mapping would change behavior for cross-system events — the ADR's own motivating scenario.
  Remediation: Either (a) expose the resolved forge platform as a variable in the overlay CEL environment (e.g., forge.platform) so overlays can faithfully replicate forge: conditioning, or (b) correct the equivalence section to document when the mapping holds and when it diverges.
• [edge-case] docs/ADRs/0088-cel-guarded-overlays.md:130 — The base composition section says mergeBaseIntoChild concatenates overlays lists, but the Decision section states that forge: and overlays: must not coexist in the same harness, enforced by Validate(). Since mergeBaseIntoChild runs before Validate(), a base harness using forge: and a child using overlays: (or vice versa) would produce a merged harness containing both, which Validate() would then reject. This creates a migration cliff: any base harness using forge: prevents all children from adopting overlays:. The ADR does not address this base composition interaction or specify whether the mutual exclusion applies to the pre-merge or post-merge result.

Low

• [stale-doc] docs/guides/user/bring-your-own-agent.md:277 — The "Forge-specific overrides" section documents the harness forge: block without noting its deprecation in favor of overlays:. Since forge: remains functional and the overlays: implementation has not landed yet, this is a follow-up item for when the implementation ships.
• [edge-case] docs/ADRs/0088-cel-guarded-overlays.md:113 — The ADR says overlay list fields use "concatenate/merge semantics from ADR 0045" but does not specify whether deduplication (as mergeSkills does via basename-keyed override) applies to overlay merges. Two matching overlay entries adding the same skill would result in duplicates unless the implementation applies dedup.
• [stale-doc] docs/contributing/harness-composition.md:37 — Documents mergeForgeBlocks without noting it supports deprecated forge: syntax. The ADR's Consequences section calls out this file as needing updates for validateOverlays, ResolveOverlays, and overlays concatenation in mergeBaseIntoChild.
• [adr-numbering-collision-risk] docs/ADRs/0088-cel-guarded-overlays.md — ADR 0088 skips from 0083 (latest on main). Verify no concurrent PRs have claimed numbers 0084–0087 before merging. The /renumber-adr skill can resolve any collision.

---

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 (3)

Review

Findings

Medium

• [edge-case] docs/ADRs/0088-cel-guarded-overlays.md:130 — The base composition section says mergeBaseIntoChild concatenates overlays lists, but the Decision section states that forge: and overlays: must not coexist in the same harness, enforced by Validate(). Since mergeBaseIntoChild runs before Validate(), a base harness using forge: and a child using overlays: (or vice versa) would produce a merged harness containing both, which Validate() would then reject. This creates a migration cliff: any base harness using forge: prevents all children from adopting overlays:. The ADR does not address this base composition interaction or specify whether the mutual exclusion applies to the pre-merge or post-merge result.
• [stale-doc] docs/guides/user/bring-your-own-agent.md:277 — The "Forge-specific overrides" section documents the harness forge: block as the primary mechanism for platform-specific configuration without mentioning that this feature is deprecated in favor of overlays: (ADR 0088). Users following this guide will adopt a deprecated pattern. The deprecation is advisory and forge: remains functional, so this is not blocking.

Low

• [edge-case] docs/ADRs/0088-cel-guarded-overlays.md:113 — The resolution pipeline runs ResolveForge before ResolveOverlays, so forge-resolved list fields are already in the base when overlays concatenate. The ADR says overlay list fields use "concatenate/merge semantics from ADR 0045" but does not specify whether deduplication (as mergeSkills does for forge resolution) applies to overlay merges. Two matching overlay entries adding the same skill would result in duplicates unless the implementation applies deduplication.
• [missing-authorization] — No issue is linked to this PR. The ADR references Add JIRA support to the triage agent #2264 and Add Jira comment write support and implement tracker.Client for Jira #5989 as motivation, and the PR body documents a direction change driven by reviewer feedback on v1. For a docs-only ADR addition, these provide reasonable implicit authorization, but formally linking one of the motivating issues would strengthen the audit trail.
• [scope-label-mismatch] — PR carries the fullsend-fix label (a CI workflow trigger for fix runs on human-authored PRs), but this is a docs-only ADR addition with no code changes to trigger fix runs against.
• [stale-doc] docs/contributing/harness-composition.md:37 — Documents mergeForgeBlocks without noting it supports deprecated forge: syntax. The ADR's Consequences section notes this file needs updating with validateOverlays, ResolveOverlays, and overlays concatenation in mergeBaseIntoChild.

Previous run (4)

Review

Findings

High

• [internal-consistency] docs/ADRs/0088-cel-guarded-overlays.md:151 — The forge-to-overlay equivalence mapping is incorrect. The ADR claims forge: github: is equivalent to overlays: - when: event.source.system == "github", but these test different things. forge: is keyed by the forge platform (detected from GITHUB_ACTIONS/GITLAB_CI env vars or the --forge CLI flag via detectForgePlatform()), which identifies the code hosting platform. event.source.system identifies the event origin (which can be jira, manual, schedule, etc. even when the forge is github). The ADR's own motivating scenario — a JIRA issue triggering work on a GitHub forge — would have forge platform = github but event.source.system = jira, so the claimed mechanical mapping would break existing forge: github: behavior for cross-system events.
  Remediation: Either (a) introduce a forge-platform variable in the CEL environment so the overlay can condition on it (when: forge.platform == "github"), or (b) correct the equivalence section to note that forge: github: does NOT map to event.source.system == "github" and describe the correct migration for each use case, or (c) define a composite CEL expression that matches the actual forge: semantics.
• [broken-link] docs/architecture.md:164 — The ADR 0088 link points to ADRs/0088-tracker-harness-config-split.md, but the actual file created in this PR is docs/ADRs/0088-cel-guarded-overlays.md. This is a stale artifact from the pre-rewrite filename and will be a broken link on merge.
  Remediation: Change the link target from ADRs/0088-tracker-harness-config-split.md to ADRs/0088-cel-guarded-overlays.md.

Low

• [missing-authorization] — No issue is linked to this PR. The ADR references Add JIRA support to the triage agent #2264 and Add Jira comment write support and implement tracker.Client for Jira #5989 as motivation, and the PR body documents a direction change driven by reviewer feedback on v1. For a docs-only ADR addition, these provide reasonable implicit authorization, but formally linking one of the motivating issues would strengthen the audit trail.
• [scope-label-mismatch] — PR carries the fullsend-fix label (a CI workflow trigger for fix runs on human-authored PRs), but this is a docs-only ADR addition with no code changes to trigger fix runs against. The component/harness and component/docs labels are appropriate.

---

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 (5)

Review

Findings

Low

• [missing-authorization] — This is a docs-only PR adding a new ADR with no executable code changes. No issue is linked, though the ADR references Add JIRA support to the triage agent #2264 and Add Jira comment write support and implement tracker.Client for Jira #5989 as motivation. Consider linking one of those issues to formalize authorization.
• [scope-coherence] docs/ADRs/0088-tracker-harness-config-split.md:54 — The ADR proposes renaming Go type ForgeConfig to PlatformConfig while the YAML key remains forge:. This introduces a naming divergence (the new tracker: YAML key would also be backed by PlatformConfig). The ADR acknowledges this as a deliberate trade-off, but worth confirming since ADR 0045's doc-comment explains why the type is currently named ForgeConfig.
• [scope-label-mismatch] — PR is labeled fullsend-fix (a CI workflow trigger for fix runs on human-authored PRs), but this is a docs-only ADR addition with no code to trigger fix runs on. The component/harness and component/docs labels are appropriate.

Previous run (6)

Review

Findings

Medium

• [api-contract] docs/ADRs/0088-tracker-harness-config-split.md:79 — The ADR states "Load() calls ResolveForge before ResolveTracker" but Load() does not call ResolveForge — it only calls Validate(). It is LoadWithOpts and LoadWithBase that perform forge resolution. If an implementer follows this ADR literally, they would modify the wrong function. Consider changing to "LoadWithOpts/LoadWithBase call ResolveForge before ResolveTracker".

Low

• [internal-consistency] docs/ADRs/0088-tracker-harness-config-split.md:106 — The Precedence Rules section enumerates list/map-shaped fields as Skills, Providers, HostFiles, RunnerEnv, Env but omits OpenShell (specifically OpenShell.Profiles), which is also concatenated in the existing mergeForgeConfig and mergeForgeConfigInto implementations. If ResolveTracker reuses the same merge logic, OpenShell.Profiles will also be concatenated from both forge and tracker blocks, but the ADR's enumeration does not account for it.
• [scope-label-mismatch] — PR is labeled fullsend-fix (a CI workflow trigger for fix runs on human-authored PRs), but this is a docs-only ADR addition with no code to trigger fix runs on. Consider adding component/harness and/or component/docs to clarify the PR's nature.

---

Labels: PR adds an ADR about the harness config schema (tracker/forge split)

[ralphbean]

Replying in reference to #6237 (comment)

Addressed the architecture.md, multiple-decisions, and Consequences-bullets findings on their own threads:

• docs!: add ADR 0088 for CEL-guarded overlays in the harness schema #6237 (comment)
• docs!: add ADR 0088 for CEL-guarded overlays in the harness schema #6237 (comment)
• docs!: add ADR 0088 for CEL-guarded overlays in the harness schema #6237 (comment)

On the "exceeds 100 lines" point — same reasoning as the multiple-decisions thread: I'm keeping this as one ADR since the rename, tracker: field, precedence rules, and runtime platform selection are all facets of one decision, so the length follows from that rather than being separately fixable.

[ralphbean]

Replying in reference to #6237 (comment)

Addressed the Load()/LoadWithOpts and OpenShell.Profiles findings on their own threads:

• docs!: add ADR 0088 for CEL-guarded overlays in the harness schema #6237 (comment)
• docs!: add ADR 0088 for CEL-guarded overlays in the harness schema #6237 (comment)

On the label point — fullsend-fix goes on every PR by convention regardless of content, and component/harness/component/docs are already on this one.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:22 PM UTC · Completed 6:38 PM UTC

Commit: eb94141 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 2:33 AM UTC · Ended 2:43 AM UTC

Commit: 51c0c2c · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 2:45 AM UTC · Completed 3:03 AM UTC

Commit: 3249e7d · View workflow run →

Superseded by updated review

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 8:32 PM UTC · Ended 8:40 PM UTC

Commit: 1c6c716 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:41 PM UTC · Completed 9:02 PM UTC

Commit: f16b496 · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[maruiz93]

I think this is a nice change. Posted some low severity comments.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 2:06 PM UTC · Completed 2:23 PM UTC

Commit: f16b496 · View workflow run →

[fullsend-ai-retro]

Retro: PR #6237 -- ADR 0088 for CEL-guarded overlays

Timeline

PR #6237 added ADR 0088 proposing CEL-guarded overlays in the harness schema. Over 4 days (Aug 14--18), the PR underwent a major architectural pivot: the original tracker/forge split design was approved by the review agent (Runs 1--2) but then rejected by human reviewer @ifireball on Aug 16, who proposed generalizing to CEL-guarded conditional sections. @ralphbean rewrote the ADR entirely on Aug 17. The review agent ran 8 times total, the fix agent was dispatched 3 times, and ~45 workflow dispatches were skipped immediately.

The review agent produced 22 findings across its runs: 7 were substantively fixed (4 by the fix agent, 3 by the author), 6 were stale duplicates of already-addressed findings (27%), 5 were deferred as follow-ups for the implementation PR, 3 were acknowledged as intentional, and 1 valid medium-severity finding (algorithm-logic-consistency contradiction in the base composition ordering section) was merged without acknowledgment.

The third fix dispatch (run 32069045748) failed silently: the pre-fetch step found a 1-byte review body and exited with "Bot-triggered run but review body is empty -- nothing to fix." No comment was posted, so the author had no signal that the fix agent did not run. Combined with the review agent's outstanding CHANGES_REQUESTED, this left the valid medium-severity finding unaddressed through merge.

Evidence for existing issues

All improvement opportunities are already tracked. Specific evidence from this PR:

• Add per-PR review budget to cap runaway review dispatches #2599, Add per-PR circuit breaker: stop dispatching after N cycles without human interaction #3034, Reduce review dispatch frequency during rapid fix-commit iterations #4069 (excessive dispatches): 8 review + 3 fix dispatches for a 2-file, 250-line docs-only PR. The review-fix cycle produced diminishing returns after the second iteration.
• Review agent should deduplicate findings across iterations on the same PR #1013, Review agent should deduplicate findings across re-review iterations on the same PR #2959 (finding deduplication): 6 of 22 findings (27%) were stale duplicates re-raised for issues already fixed in intermediate commits, wasting review output space and triggering unnecessary fix cycles.
• Fix agent cannot find review findings and fails silently on retry #4675 (fix agent cannot find review findings): The third fix dispatch failed because the pre-fetched review body was empty (1 byte), leaving the review agent's CHANGES_REQUESTED unresolved with no user feedback.
• Fix agent should post a PR comment when /fix produces no changes #2597 (fix agent silent no-op): No comment was posted when the fix agent failed to produce changes, leaving the author unaware the finding was unaddressed.
• Review bot CHANGES_REQUESTED did not block merge of PR with known correctness bug #1201 (CHANGES_REQUESTED merged without acknowledgment): The review bot's final run gave CHANGES_REQUESTED with a valid medium-severity finding about a base-composition ordering contradiction; the PR merged 17 hours later with two human approvals but no acknowledgment of the bot finding.
• Review agent approved initial commit with zero findings despite multiple correctness bugs #4305, Review agent should withhold ready-for-merge label when it detects advisory-level concerns in approved PRs #4463 (false positive approval): The review agent approved the original tracker/forge split design (Runs 1--2) that was subsequently rejected by a human reviewer as architecturally unsound.
• Review agent should comment-only (not approve) on ADR PRs #1659, Review agent should deprioritize findings on planning/design documents #2678 (docs/ADR review quality): Low-value PR-metadata findings (scope-label-mismatch, missing-authorization) recurred across multiple runs on this docs-only PR.
• Review skill: detect omissions in ADRs, specs, and design documents by exploring project context #1906 (design omission detection): Human reviewer @maruiz93 identified substantive implementation gaps (CEL compilation caching, runtime error semantics, naming convention inconsistencies) that the review agent did not surface.

Autonomy readiness

The review agent reliably detected broken links, internal prose inconsistencies, and API reference errors -- high-value mechanical checks for docs PRs. However, it approved an architecturally flawed design (Runs 1--2) that a human reviewer correctly rejected, and it could not surface implementation feasibility concerns that human reviewers identified. For ADR PRs proposing new architecture, human review remains essential and the review agent's approval should not be treated as a quality signal for design soundness.

No new proposals

All identified improvements are tracked by existing issues. No novel proposals are warranted.