Skip to content

docs(adr): use tracker-first dispatch for multiple targets - #9266

Draft
eshulman2 wants to merge 2 commits into
fullsend-ai:mainfrom
eshulman2:docs/adr-0167-multi-target
Draft

eshulman2 wants to merge 2 commits into
fullsend-ai:mainfrom
eshulman2:docs/adr-0167-multi-target

Conversation

@eshulman2

@eshulman2 eshulman2 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

When one request maps to several maintained branches, a trusted workflow adapter creates or reuses one investigation ticket per authorized target before applicability is known. It then schedules ordinary single-target Fullsend triage and retains case-wide bounds and accounting. This ADR chooses that initial route instead of requiring a new native multi-target runner interface.

Related Issue

Integration and acceptance are tracked in #9260. Durable recovery remains separate in #9253 / PR #9264, and strict Pi tool selection remains in #9254 / PR #9265. This documentation PR implements none of those capabilities and closes no implementation issue.

Changes

  • Rename and rewrite unmerged ADR 0167 as 0167-use-tracker-first-dispatch.md; no ADR accepted on main is rewritten.
  • Create/reuse a target tracker first, with applicability unknown and stable identity independent of an attempt's source SHA. A pre-tracker discovery assessment is not required.
  • Populate trusted single-target intake and use an authorized triage dispatch path. A bot cannot impersonate a human command; unsupported authorization or source binding stays visibly blocked.
  • Reuse per-subject concurrency for separate target tickets while the adapter enforces case-wide limits, source verification, recovery and aggregate accounting.
  • Separate ticket publication, scheduling and triage receipts. Failed or uncertain work remains attached to the same investigation ticket and grants no coding authority.
  • Retain complete target coverage through mapping/source/policy changes, without treating ticket creation as successful assessment or resetting consumed bounds.
  • Update the problem document's alternatives, acceptance criteria and open questions, plus the living architecture and reciprocal context links.

The initial tracker adapter uses Jira for source targets on GitHub, GitLab or Forgejo only where the selected single-target execution path verifies source identity and authorization. Unsupported combinations stay blocked. Domain mapping and Jira rendering stay in the consumer adapter; this decision does not add a generic queue, native multi-target scheduler or plan/result API to Fullsend.

Current-behavior evidence

Inspected source baseline: ef7c61ec1e703f5032ccac96201f107f6b1ec3f6.

  • harnessdispatch.Dispatch applies configured authorization and matches harnesses for an event.
  • ProjectExecutionRef maps the matched harness and work-item event to an individual execution record.
  • jirapoll.Run supplies Jira work-item routing while documenting the shell scheduling-acknowledgement gap; this proposal does not claim publication or distributed recovery is already complete.
  • Jira integration guide describes the existing per-work-item dispatch integration.
  • ADR 0106 is the per-harness/repository/subject serialization decision; this route uses distinct target tickets rather than inventing target identities inside a shared subject's concurrency key.

Testing

  • Changes staged before make lint; applicable ADR, Markdown link, secret and Semgrep checks pass.
  • git diff --check passes.
  • Documentation only: no new worker, Jira publication or distributed recovery acceptance is claimed.

Checklist

  • Conventional Commit title.
  • Human-directed commit signed off for DCO.
  • I wrote this contribution myself and can explain all changes in it.

Prepared with coding-agent assistance; the contributor can assess the personal-authorship attestation.

Signed-off-by: eshulman2 <ellashulman1@gmail.com>
@eshulman2
eshulman2 requested a review from a team as a code owner November 10, 2026 10:08
@github-actions

Copy link
Copy Markdown

E2E tests did not run

E2E tests run automatically for pull requests authored by users with write access or higher.

For other contributors, someone with write access must add the ok-to-test label after the latest push.

Reason: unauthorized

See E2E testing guide for details.

@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Define authorized multi-target execution in ADR 0167

📝 Documentation 🕐 20-40 Minutes

Grey Divider

AI Description

• Record the decision to use bounded, host-admitted plans for authorized multi-target execution.
• Define isolated target work, exact result binding, complete accounting, and plan supersession.
• Link the decision into the living architecture; implementation remains separate.
Diagram

graph TD
  A["Trusted adapter"] --> B{"Host admission"} -->|authorized| C["Frozen plan"] --> D["Isolated children"] --> E["Attempt validation"] --> F{"Coverage complete"}
  B -->|blocked| G["Blocked target"]
  C -->|inputs change| H["Superseding plan"]
  H --> B
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Workflow-owned CI matrices
  • ➕ Reuse familiar CI job launching without a plan interface.
  • ➖ Each workflow must independently enforce authorization, target identity, bounds, and complete accounting.
2. Model-led coordination
  • ➕ Can propose targets and investigation steps flexibly.
  • ➖ Model choices cannot establish execution authority or deterministic coverage.

Recommendation: Keep the ADR’s host-admitted plan boundary while reusing existing dispatch and CI execution. It centralizes authorization and accounting without introducing a second scheduler or granting authority to model output.

Files changed (5) +195 / -0

Documentation (5) +195 / -0
0167-execute-authorized-multi-target-plans.mdAdopt bounded, authorized multi-target plans +106/-0

Adopt bounded, authorized multi-target plans

• Records the decision to freeze target scope, identity, source, policy, and execution bounds before dispatch. Defines child isolation, exact-attempt result validation, complete accounting, supersession, and cross-forge conformance while leaving durable recovery separate.

docs/ADRs/0167-execute-authorized-multi-target-plans.md

architecture.mdRegister the multi-target decision in the architecture +6/-0

Register the multi-target decision in the architecture

• Adds the decided-but-unimplemented plan boundary, target-aware scheduling, and required-target accounting, with a link to ADR 0167.

docs/architecture.md

agent-architecture.mdConnect repository coordination to multi-target coverage +5/-0

Connect repository coordination to multi-target coverage

• Links the multi-target problem and ADR from the repository-as-coordinator discussion, noting that host-admitted plans preserve independent worker roles.

docs/problems/agent-architecture.md

agent-infrastructure.mdConnect worker infrastructure to target isolation +6/-0

Connect worker infrastructure to target isolation

• Links the multi-target problem and ADR where isolated contexts and target-aware scheduling affect worker execution.

docs/problems/agent-infrastructure.md

multi-target-execution.mdDocument multi-target failure cases and acceptance criteria +72/-0

Document multi-target failure cases and acceptance criteria

• Describes authorization, identity, collision, missing-result, and supersession failures. Compares CI matrices, model-led coordination, and host-admitted plans, then records acceptance scenarios and open interface questions.

docs/problems/multi-target-execution.md

@qodo-code-review

qodo-code-review Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Grey Divider


Remediation recommended

1. Mid-sentence product name breaks the documented casing rule ⊘ Outdated
Description
The Consequences section of ADR 0167 writes Fullsend with a capital F in the middle of a sentence
("while Fullsend enforces execution boundaries"). The documentation guide asks for lowercase
fullsend in running prose and capital Fullsend only at the start of a sentence or in titles and
headings. The deviation is in a new ADR that other readers will cite, so the wrong casing will be
copied into later docs.

2. New ADR paragraph runs well past the wrap width ⊘ Outdated
Description
The Decision paragraph of ADR 0167 has one line of about 92 characters ("case store and artifact
namespace, bound to its plan, target, action and attempt. Scheduling"), while the rest of the prose
is wrapped near 80 columns. The contributing guide asks for prose wrapped near 80 columns so that
later one-word edits produce small diffs. This line breaks that pattern in a file added by this PR.


Informational

3. Accepted ADR assumes existing dispatch enforces plan bounds ⊘ Outdated
Description
The Decision states that existing dispatch and CI mechanisms launch children under the plan's
concurrency, target-count, attempt and time bounds, but the PR's own current-behavior evidence says
WriteGHAMatrix emits execution rows rather than a frozen plan or collection barrier. Implementers
reading this Accepted ADR may assume the bounds and per-child identity are already enforced by
existing matrix or dispatch code, so the new plan layer could be skipped or built on a mechanism
that does not enforce those limits.

Grey Divider

Context sources
✅ Linked PRs:
  🌐 PR #9261
❌ Tickets: failed to load — Ticket collection could not establish complete evidence
✅ Compliance rules (platform): 96 rules
✅ Skills: 5 invoked
  writing-user-docs
  writing-adrs
  check-patch-coverage
  cutting-releases
  adr-corner
✅ Cross-repo context — repo relationships
✅ REVIEW.md
Review mode: Auto: 🚀 Fast: Docs-only ADR and links; no runtime change, one light pass.

Grey Divider

Tip of the day
💡 Did you know, you can move or hide resolved findings to focus on what still needs action

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@eshulman2
eshulman2 marked this pull request as draft November 10, 2026 11:19
Signed-off-by: eshulman2 <ellashulman1@gmail.com>
@eshulman2 eshulman2 changed the title docs(adr): define authorized multi-target execution docs(adr): use tracker-first dispatch for multiple targets Nov 10, 2026

@ascerra ascerra left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is the right shape: one tracker per target, then a normal single-target run, with nothing new in the runner.

I tested the single-target half on a GitLab project with Jira trackers (notes). I didn't build the adapter, so I have nothing on that from experience.

Four things came out of it, inline.

Comment on lines +48 to +49
Use tracker-first dispatch to assess each authorized source target through an
ordinary single-target Fullsend triage run.

@ascerra ascerra Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I read "ordinary triage" as the stock agent, though in the experiment it is really a CVE assess harness registered as triage. Two things from testing:

  • Stock triage picked up a vulnerability tracker and tried to close it as not planned, so it has to be kept off these trackers.
  • Registering the assess harness as triage means the repo loses regular triage, which adopting teams will still want.

What worked was a separate agent that uses the triage role. Suggest "a single-target assessment harness that uses the triage role", here and at line 101.

I put that up as its own cve agent in a draft ADR, #9309, so it would help if this one didn't assume the triage name, let's discuss this some more.

Comment on lines +62 to +66
The adapter populates the supported single-target intake from trusted mapping
and advisory data, then schedules triage through an authorized dispatch path.
A bot comment cannot impersonate a human command or bypass the harness actor
minimum. If no supported path can authorize triage, the tracker remains
visibly pending authorization. Each run verifies its actual origin, branch

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I couldn't find a path either. The Jira poller drops events from its own account, app accounts and automation-looking names (filterBotEvents in internal/jirapoll/poller.go), so a tracker the adapter creates never dispatches.

In my testing a person started every run, and the experiment's trigger also wants a person to comment. That seems fine for a first version.

Could the decision say so plainly: a person starts each run, and the adapter doesn't schedule yet?

Comment on lines +66 to +68
visibly pending authorization. Each run verifies its actual origin, branch
and source revision against the selected intake; a release target must not
silently fall back to the default branch. The run owns its checkout, context,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with the rule, but nothing gives a run its branch today. The dispatch record has no ref (ExecutionRef in internal/harnessdispatch/ref.go), and Jira-sourced runs use "the pinned default branch".

So the pre-script has to fetch and check out the branch, as the experiment does and I did (code). That swapped out the run's own .fullsend directory and cost me a published verdict on v0.55.0, until I restored the checkout (code).

Could the ADR pick one: a ref on the dispatch (a core change), or the harness does it and must restore the checkout?

Comment on lines +86 to +88
bounds do not silently reset. Domain mapping, Jira rendering and aggregate
accounting remain in the workflow adapter. This initial route introduces no
native Fullsend multi-target scheduler or plan/result API. Later platform

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keeping the workflow generic is what we want, so I like this. Two things I'd add to the ADR:

  • What changes in fullsend or the agents repo. From testing: an assessment harness, a way to start a run on a tracker automation created, and a branch for the run.
  • Where the adapter lives and how a second team gets it. Is there a consumer besides CVE yet?

Also, I have nothing for getting from a tracker to its repo and branch. Is the experiment's release-mappings.yaml format the adapter's business, or something fullsend should define?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants