docs: add ADR 0088 for tracker/forge harness config split

[ralphbean]

Summary

• Adds tracker: as a harness key sibling to forge:, so a code agent can read from one tracker (e.g. JIRA) while writing to an unrelated forge (GitHub/GitLab).
• Renames internal/harness.ForgeConfig to PlatformConfig and generalizes both existing merge pipelines (forge.go resolution, compose.go base: composition) to operate on either forge: or tracker:, rather than duplicating them.
• Fixes scalar merge order to be explicit (forge then tracker, tracker wins on conflict) instead of leaving it as call-order accident.
• Motivated by the fullsend-ai/agents add-jira-tracker-support OpenSpec change, which depends on this schema/runtime piece landing here first.

Test plan

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

[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://3844b807-site.fullsend-ai.workers.dev

Commit: eb941418f1dbb01f340fcd88172e701ac27dbca2

[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 (2)

1. docs/architecture.md missing ADR 0088 📜 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 describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[fullsend-ai-review]

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

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 tracker/forge harness config split #6237 (comment)
• docs: add ADR 0088 for tracker/forge harness config split #6237 (comment)
• docs: add ADR 0088 for tracker/forge harness config split #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 tracker/forge harness config split #6237 (comment)
• docs: add ADR 0088 for tracker/forge harness config split #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]

[low] scope-coherence

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 doc-comment explains why the type is currently named ForgeConfig.