Skip to content

docs(adr): define entity source bindings and execution integration - #9199

Open
ifireball wants to merge 3 commits into
mainfrom
codex/entity-source-bindings
Open

ifireball wants to merge 3 commits into
mainfrom
codex/entity-source-bindings

Conversation

@ifireball

@ifireball ifireball commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Summary

The current tracker mapping selects at most one issue provider and its creation policy; it cannot express multiple service instances or per-agent entity scopes. ADR 0079 adopts named connections and sources, with typed harness slots bound by repository configuration, to connect entity discovery, agent coordination, CI integration, and the existing run modes.

This is a documentation-only proposal. The versioned contract now defines connection defaults, native-source resolution, query membership, destination policy, and migration. Implementation and activation remain subject to the entity, discovery, authorization, and context prerequisites.

Related Issue

Relates to #8418, #8420, and #8421; this PR does not close implementation work. The current tracker mapping comes from issue #9074; the Jira connection and polling additions come from PR #9091. The proposed named-source structure follows the review discussion.

Changes

  • Define named connections and sources, harness entity_kinds slots, list-valued agents[].entities bindings, and provider-specific harness filters. Only source schedules work; an omitted target binding follows the effective source binding.
  • A source with no connection uses the connection with the same name. Reserved provider sources must use their same-named connection; configure that connection's trusted endpoint to select another instance. Only the origin provider's reserved source may inherit the clone's repository path.
  • Bind endpoint credentials to the canonical host and tenant; untrusted config cannot redirect them. Clarify provider-native membership and source scope checks. GitLab closed for merge requests expands to the native closed and merged states.
  • Explain entity-state coordination, CI responsibilities, integration with ADR 0144's run modes, standalone issue selection, and migration from tracker, including the allowed_targets destination for provider-only legacy blocks.
  • State that v1 has no in-band config version field, older strict readers reject new keys, and all readers must be upgraded before emitting them. Keep tracker translation until all supported consumers migrate; removal needs a later ADR and major-release migration window.
  • Update the architecture, related problem documents, and config reference. ADR 0098 receives a short refinement annotation. ADR 0149 is partially superseded for source-membership semantics; its combined search, coverage, and retry requirements remain.

Current-behavior evidence

Verified at commit 3ac6aea526f7b2b60db667645cbb2bed81236f4a:

Testing

  • Staged changes and ran make lint: documentation status, number, frontmatter, links, formatting, and secret checks passed. Optional Semgrep skipped because its cache directory was read-only; no security analysis is claimed.
  • Checked ADR numbering against current main and all 170 open PRs; no collision.
  • git diff --check passed.
  • Runtime tests are not applicable: no implementation code changes.

Checklist

  • PR title follows Conventional Commits (docs(adr)).
  • Commit includes Barak Korren's DCO sign-off and agent attribution.
  • Current and proposed behavior are distinguished; implementation remains in follow-up work.

Record named connections, entity sources, typed harness slots, and provider
filters as the configuration model for entity-driven execution. Explain
native source resolution, CI integration, run modes, destination policy,
and compatible migration from tracker.

Add the versioned configuration contract and update the architecture,
problem documents, and configuration reference.

Signed-off-by: Barak Korren <bkorren@redhat.com>
Assisted-by: Codex
@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Define entity-source bindings and execution integration

📝 Documentation 🕐 40+ Minutes

Grey Divider

AI Description

• Adopt named connections, entity sources, and typed harness bindings for multi-provider entity
 execution.
• Specify provider selection, admission checks, CI responsibilities, and compatibility with existing
 run modes.
• Define migration from tracker while keeping implementation and activation subject to
 prerequisite contracts.
Diagram

graph TD
  Origin["Configuration origin"] --> Connections["Named connections"] --> Sources["Entity sources"] --> Bindings["Slot bindings"] --> Selection["Discovery checks"] --> Admission["Admission gates"] --> Run["CI execution"]
  Filters["Harness filters"] --> Selection
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Extend the existing tracker mapping
  • ➕ Preserves a familiar configuration shape and reduces immediate migration work.
  • ➖ The single-provider mapping does not naturally represent multiple instances, reusable scopes, or per-agent typed inputs and outputs.
2. Route agents through a CI workflow graph
  • ➕ Makes agent sequencing explicit in existing CI configuration.
  • ➖ Duplicates selection logic across platforms and shifts coordination away from observable entity state.

Recommendation: Use the proposed separation of connections, sources, and harness bindings. It supports multiple providers while keeping harnesses portable and CI focused on execution; in-memory tracker translation provides a migration path. Review activation only alongside the outstanding discovery, authorization, entity, and context contracts.

Files changed (8) +1305 / -9

Documentation (8) +1305 / -9
0079-bind-entity-execution-through-named-sources.mdAdopt named sources for entity-driven execution +459/-0

Adopt named sources for entity-driven execution

• Records the decision to bind typed harness slots to repository-defined connections and sources rather than extend the single-provider 'tracker' model. Defines native resolution, provider selection, CI responsibilities, run-mode integration, destination behavior, and migration boundaries.

docs/ADRs/0079-bind-entity-execution-through-named-sources.md

0098-entity-first-harness-evaluation.mdAnnotate entity evaluation with ADR 0079 refinements +5/-0

Annotate entity evaluation with ADR 0079 refinements

• Links the existing entity-first decision to typed slots and repository-owned bindings. Clarifies that provider-native membership is a separate gate from actor-filtered CEL and model-context admission.

docs/ADRs/0098-entity-first-harness-evaluation.md

0149-coalesce-entity-source-discovery-queries.mdMark local membership requirements as partially superseded +7/-0

Mark local membership requirements as partially superseded

• Notes that ADR 0079 permits exact local or batched provider-native membership checks instead of requiring local reproduction over actor-filtered data. Retains combined enumeration, coverage, retry, and independent admission requirements.

docs/ADRs/0149-coalesce-entity-source-discovery-queries.md

architecture.mdDescribe the target binding and discovery architecture +50/-9

Describe the target binding and discovery architecture

• Adds the target configuration, native-source resolution, harness filters, and division of responsibilities between Fullsend and CI. Revises discovery guidance to distinguish provider-native membership from authorization and identifies contracts still needed for activation.

docs/architecture.md

README.mdSpecify the entity-source configuration v1 contract +755/-0

Specify the entity-source configuration v1 contract

• Defines validation, layering, defaults, provider query subsets, source membership, destination policy, standalone issue selection, and legacy 'tracker' translation. Sets execution-readiness, cutover, and conformance requirements while explicitly identifying the contract as not yet implemented.

docs/normative/entity-source-configuration/v1/README.md

agent-architecture.mdConnect agent coordination to source bindings +14/-0

Connect agent coordination to source bindings

• Relates typed slots and provider-native discovery checks to entity-state coordination. Clarifies that CI executes admitted work without introducing an agent workflow graph.

docs/problems/agent-architecture.md

agent-infrastructure.mdRecord the CI and recurring-discovery decision +1/-0

Record the CI and recurring-discovery decision

• Marks the question of supporting entity-bound resident runs through CI as decided by ADR 0079, subject to verified discovery readiness and ADR 0144 lifecycle rules.

docs/problems/agent-infrastructure.md

config-reference.mdPoint tracker users to the proposed replacement +14/-0

Point tracker users to the proposed replacement

• Links to ADR 0079 and the versioned contract, summarizing named sources, native resolution, and planned compatibility translation. Explicitly states that 'tracker' remains the currently supported configuration.

docs/reference/config-reference.md

@ifireball ifireball self-assigned this Nov 8, 2026
@qodo-code-review

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

Copy link
Copy Markdown

Code Review by Qodo

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

Grey Divider


Remediation recommended

1. Open infrastructure question is marked decided early ✓ Resolved

Resolving commit: 7fd1769

Resolution reason
The strike-through and "Decided" wording were removed from the question in
docs/problems/agent-infrastructure.md. It is now an open question, with the design direction
described as decided in ADR 0079 and "Required contracts, adapters, and rollout remain open." This
addresses the overstated status.
Description
The agent-infrastructure problem record strikes through the CI and recurring-discovery question as
decided by ADR 0079. The ADR is only a target design, and its own activation section requires the
normalized-entity, discovery-protocol, and authorization contracts that are still pending, so the
strike-through overstates status.

2. GitLab closed preset mismatches native MR state ✓ Resolved

Resolving commit: 7fd1769

Resolution reason
Redefined GitLab's change-proposal closed preset as the union of native state=closed and
state=merged queries, matching GitLab's REST API semantics, and added the matching conformance
case. Also updated the ADR 0079 text accordingly.
Description
The contract defines GitLab's closed preset for change proposals as including merged MRs, but
GitLab's REST state filter treats closed and merged as separate values. The contract also says
native provider semantics determine membership, so a closed source would select a different set
than GitLab's own state=closed filter.

3. Context cites ADRs without links ✓ Resolved

Resolving commit: 7fd1769

Resolution reason
The Context paragraph was rewritten so each ADR reference is now a relative Markdown link: [ADR
0098](0098-entity-first-harness-evaluation.md), [ADR
0144](0144-reuse-poll-and-entity-bound-run-processes.md), and [ADR
0149](0149-coalesce-entity-source-discovery-queries.md). This matches the suggested fix exactly,
with wording otherwise unchanged.
Description
The Context paragraph says `ADRs 0098, 0144, and 0149 define entity evaluation, reusable run
processes, and combined discovery` with bare numbers and no Markdown links, although the Status
annotations link all three. The checklist requires an explicit cross-reference link in Context, so a
reader of the Context section cannot follow the dependency on 0149 and the refinement of 0098
without leaving the paragraph.

View medium (2)
4. Connection endpoints can redirect discovery credentials ✓ Resolved

Resolving commit: 7fd1769

Resolution reason
States which configuration layers are trusted to set connection endpoints (managed repos.yaml and
protected-default-branch .fullsend/ config; not PR-head config, harness content, or event data),
requires credential bindings to be scoped to the exact canonical endpoint and tenant, forbids
sending a credential to any other endpoint, and specifies that changing an endpoint invalidates the
previous credential binding. Adds matching conformance requirements.
Description
The contract lets a layered connection setting change a native provider's base_url, but it never
says which configuration layers are trusted to set it or that a changed endpoint must drop the
credential binding. Its endpoint-change rule only forbids transferring grants and cached evidence,
so a repository-level connections.github.base_url could point discovery at an attacker-controlled
host while the same credential is still sent. The rule should also cover credentials, and the
trusted-layer requirement needs to be stated.

5. Current tracker behavior in ADR 0079 lacks an introducing link ✓ Resolved

Resolving commit: 7fd1769

Resolution reason
The Context sentence now reads "The current tracker mapping selects one issue backend and its
issue-creation policy, as specified in [issue
#9074](https://github.com/fullsend-ai/fullsend/issues/9074)." This adds a provenance link to the
issue that specified the tracker mapping, directly in the flagged sentence, and keeps the PR #9091
link for the Jira fields. The Options-section link was not added, but the primary Context
requirement is met.
Description
The ADR's Context states what the current tracker mapping does (one issue backend and its
issue-creation policy) without linking the PR, issue, or ADR that introduced that mapping. The only
link in that paragraph, PR #9091, covers the Jira connection and polling fields, not the tracker
block itself, so a reader cannot trace when or why this current behavior was introduced. The Options
section repeats this for the current syntax, and the PR description's commit-pinned evidence does
not substitute for an introducing link inside the ADR.


Informational

6. Partial supersession is described as preservation 🐞 Bug ⚙ Maintainability
Description
The ADR 0149 annotation says ADR 0079 partially supersedes its local-reproduction and actor-filtered
requirements, yet the PR description says the original decisions are preserved. A later reader of
ADR 0149 alone may still treat the superseded rules as binding.
Code

docs/ADRs/0149-coalesce-entity-source-discovery-queries.md[R28-30]

+[ADR 0079](0079-bind-entity-execution-through-named-sources.md) partially
+supersedes the local-reproduction and actor-filtered source-query requirements:
+membership follows native provider semantics, with exact local checks where
Relevance

●● Moderate

Annotation-style supersession fixes are sometimes accepted, but status-line format requests were
rejected; evidence is weak either way.

PR-#8698
PR-#6956

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The accepted ADR's decision is superseded in part, but the status line stays Accepted with no
supersession marker, which makes the rule change easy to miss.

Dismiss ↗ | View ↗


Grey Divider

Context sources
✅ Linked PRs:
  🌐 PR #9091
✅ Compliance rules (platform): 96 rules
✅ Skills: 5 invoked
  writing-user-docs
  writing-adrs
  check-patch-coverage
  cutting-releases
  adr-corner
✅ Web pages:
  +2 more
✅ Cross-repo context — repo relationships
✅ REVIEW.md
Review mode: Auto: 🚀 Fast: Documentation-only ADR and normative proposal; no runtime or config code changes.

Grey Divider

Tip of the day
💡 Did you know, you can pick a display mode instead of tweaking every Display option by hand

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

Comment thread docs/problems/agent-infrastructure.md Resolved
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:16 PM UTC · Completed 8:28 PM UTC

Commit: 427c80b · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $3.02

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

Site preview

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

Commit: 31c0a9fc0073d73bf6b1714f910dba118004d4ad

@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Nov 8, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Documentation-only architectural change with no protected paths or code changes; large diff size and high churn on central documentation files are balanced by additive specification scope and low risk metadata.

Previous run

Risk Assessment: moderate (2/5)

Details

Documentation-only architectural change with no protected paths or code changes; large diff size and high churn on central documentation files are balanced by additive specification scope and low risk metadata.

Previous run (2)

Risk Assessment: moderate (2/5)

Details

Documentation-only architectural change with no protected paths or code changes; large diff size and high churn on central documentation files are balanced by additive specification scope and low risk metadata.

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

Looks good to me

Earlier findings

  • docs/normative/entity-source-configuration/v1/README.md:335, api-contract, resolved: the actionable_work example omits repositories, and the revised default-scope rule (README lines 145-151, 354-358) now allows that for sources resolving to the origin provider-default connection.
  • docs/normative/entity-source-configuration/v1/README.md (PR-level), backward-incompatible, reclassified to info: the spec itself states the no-in-band-version constraint, and the latest change does not alter it.

No findings at or above low severity; 1 lower-severity finding(s) were not posted.

Previous run

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJyZXF1ZXN0LWNoYW5nZXMiLCJmaW5kaW5ncyI6W3sic2V2ZXJpdHkiOiJtZWRpdW0iLCJjYXRlZ29yeSI6ImFwaS1jb250cmFjdCIsImZpbGUiOiJkb2NzL25vcm1hdGl2ZS9lbnRpdHktc291cmNlLWNvbmZpZ3VyYXRpb24vdjEvUkVBRE1FLm1kIiwiaWQiOiJmXzE5MDFlN2RkZWM4ODFiMWYiLCJsaW5lIjozMzUsImFjdGlvbmFibGUiOnRydWUsImRpbWVuc2lvbiI6ImNvcnJlY3RuZXNzIn0seyJzZXZlcml0eSI6ImluZm8iLCJjYXRlZ29yeSI6ImJhY2t3YXJkLWluY29tcGF0aWJsZSIsImZpbGUiOiJkb2NzL25vcm1hdGl2ZS9lbnRpdHktc291cmNlLWNvbmZpZ3VyYXRpb24vdjEvUkVBRE1FLm1kIiwiaWQiOiJmX2Y0MmFlZWFlMjY2NGRlMWEiLCJhY3Rpb25hYmxlIjpmYWxzZSwiZGltZW5zaW9uIjoiY3Jvc3MtcmVwby1jb250cmFjdHMifSx7InNldmVyaXR5IjoibWVkaXVtIiwiY2F0ZWdvcnkiOiJhcGktY29udHJhY3QiLCJmaWxlIjoiZG9jcy9ub3JtYXRpdmUvZW50aXR5LXNvdXJjZS1jb25maWd1cmF0aW9uL3YxL1JFQURNRS5tZCIsImlkIjoiZl9hNGE2YTVmM2UyMjRlMTAzIiwibGluZSI6MTIzLCJhY3Rpb25hYmxlIjp0cnVlLCJkaW1lbnNpb24iOiJjb3JyZWN0bmVzcyJ9LHsic2V2ZXJpdHkiOiJsb3ciLCJjYXRlZ29yeSI6ImRvYy1zdHlsZSIsImZpbGUiOiJkb2NzL0FEUnMvMDA3OS1iaW5kLWVudGl0eS1leGVjdXRpb24tdGhyb3VnaC1uYW1lZC1zb3VyY2VzLm1kIiwiaWQiOiJmX2IyNmNlM2Q1MjZjOTk3NGEiLCJsaW5lIjoyNDYsImFjdGlvbmFibGUiOnRydWUsImRpbWVuc2lvbiI6InN0eWxlLWNvbnZlbnRpb25zIn0seyJzZXZlcml0eSI6ImxvdyIsImNhdGVnb3J5IjoiZG9jLXN0eWxlIiwiZmlsZSI6ImRvY3Mvbm9ybWF0aXZlL2VudGl0eS1zb3VyY2UtY29uZmlndXJhdGlvbi92MS9SRUFETUUubWQiLCJpZCI6ImZfMzgwODA4YjY3ODQ1MmRiZSIsImxpbmUiOjc3LCJhY3Rpb25hYmxlIjp0cnVlLCJkaW1lbnNpb24iOiJzdHlsZS1jb252ZW50aW9ucyJ9LHsic2V2ZXJpdHkiOiJsb3ciLCJjYXRlZ29yeSI6ImRvYy1zdHlsZSIsImZpbGUiOiJkb2NzL3Byb2JsZW1zL2FnZW50LWluZnJhc3RydWN0dXJlLm1kIiwiaWQiOiJmXzUxNjdkYWU2ZjZiNzUyM2EiLCJsaW5lIjoxMjksImFjdGlvbmFibGUiOnRydWUsImRpbWVuc2lvbiI6InN0eWxlLWNvbnZlbnRpb25zIn0seyJzZXZlcml0eSI6ImxvdyIsImNhdGVnb3J5IjoiZG9jLXN0eWxlIiwiZmlsZSI6ImRvY3MvQURScy8wMDc5LWJpbmQtZW50aXR5LWV4ZWN1dGlvbi10aHJvdWdoLW5hbWVkLXNvdXJjZXMubWQiLCJpZCI6ImZfOWZkZDgzM2M5YmQzNzUxMiIsImxpbmUiOjQ1NSwiYWN0aW9uYWJsZSI6dHJ1ZSwiZGltZW5zaW9uIjoic3R5bGUtY29udmVudGlvbnMifSx7InNldmVyaXR5IjoibG93IiwiY2F0ZWdvcnkiOiJtaXNzaW5nLWRlcHJlY2F0aW9uIiwiZmlsZSI6ImRvY3Mvbm9ybWF0aXZlL2VudGl0eS1zb3VyY2UtY29uZmlndXJhdGlvbi92MS9SRUFETUUubWQiLCJpZCI6ImZfMWQ2NTNlZmFlMjQ5NzkyNCIsImFjdGlvbmFibGUiOmZhbHNlLCJkaW1lbnNpb24iOiJjcm9zcy1yZXBvLWNvbnRyYWN0cyJ9LHsic2V2ZXJpdHkiOiJsb3ciLCJjYXRlZ29yeSI6Im1pc3NpbmctdmVyc2lvbi1idW1wIiwiZmlsZSI6ImRvY3Mvbm9ybWF0aXZlL2VudGl0eS1zb3VyY2UtY29uZmlndXJhdGlvbi92MS9SRUFETUUubWQiLCJpZCI6ImZfODVkYWExMmI1ZDdkZTI1OCIsImFjdGlvbmFibGUiOmZhbHNlLCJkaW1lbnNpb24iOiJjcm9zcy1yZXBvLWNvbnRyYWN0cyJ9XSwiZGlzcG9zaXRpb25zIjpbeyJpZCI6ImZfYTRhNmE1ZjNlMjI0ZTEwMyIsInN0YXR1cyI6InJlc29sdmVkX2J5X2NoYW5nZSJ9LHsiaWQiOiJmX2IyNmNlM2Q1MjZjOTk3NGEiLCJzdGF0dXMiOiJyZXNvbHZlZF9ieV9jaGFuZ2UifSx7ImlkIjoiZl8zODA4MDhiNjc4NDUyZGJlIiwic3RhdHVzIjoicmVzb2x2ZWRfYnlfY2hhbmdlIn0seyJpZCI6ImZfNTE2N2RhZTZmNmI3NTIzYSIsInN0YXR1cyI6InJlc29sdmVkX2J5X2NoYW5nZSJ9LHsiaWQiOiJmXzlmZGQ4MzNjOWJkMzc1MTIiLCJzdGF0dXMiOiJyZXNvbHZlZF9ieV9jaGFuZ2UifSx7ImlkIjoiZl8xZDY1M2VmYWUyNDk3OTI0Iiwic3RhdHVzIjoicmVzb2x2ZWRfYnlfY2hhbmdlIn0seyJpZCI6ImZfODVkYWExMmI1ZDdkZTI1OCIsInN0YXR1cyI6InJlc29sdmVkX2J5X2NoYW5nZSJ9LHsiaWQiOiJmX2Y0MmFlZWFlMjY2NGRlMWEiLCJzdGF0dXMiOiJyZWNsYXNzaWZpZWQifV19 -->

Review

Findings

Medium

  • [api-contract] docs/normative/entity-source-configuration/v1/README.md:335 — The actionable_work example omits repositories, but the revised source-resolution rules (lines 145-151) permit that omission only for the reserved source whose provider matches the configuration origin. actionable_work is an ordinary source actively bound via agents[].entities.source, so a conforming implementation must reject this advertised configuration instead of inheriting the clone's repository path.
    Remediation: Add an explicit repositories list to actionable_work, using an illustrative owner/repository path.

Earlier findings

  • docs/normative/entity-source-configuration/v1/README.md:123, api-contract — resolved: same-name connection defaults and origin-only clone-path inheritance are now defined (lines 136-152, 231-239).
  • docs/ADRs/0079-bind-entity-execution-through-named-sources.md:246, doc-style — resolved: "Fullsend" lowered in prose (lines 245-257).
  • docs/normative/entity-source-configuration/v1/README.md:77, doc-style — resolved: capitalization fixed (line 83).
  • docs/problems/agent-infrastructure.md:129, doc-style — resolved: capitalization fixed.
  • docs/ADRs/0079-bind-entity-execution-through-named-sources.md:455, doc-style — resolved: bullets reflowed (lines 464-473).
  • docs/normative/entity-source-configuration/v1/README.md, missing-deprecation — resolved: tracker removal policy stated (later ADR plus major-release migration window).
  • docs/normative/entity-source-configuration/v1/README.md, missing-version-bump — resolved: spec states the v1 label adds no config version field and adds a conformance bullet for old strict readers.
  • docs/normative/entity-source-configuration/v1/README.md, backward-incompatible — reclassified to info: documented upgrade-readers-first rollout with key-specific diagnostics and a conformance case.

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

1 finding(s) below the low severity threshold were not posted.

Previous run (2)

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJyZXF1ZXN0LWNoYW5nZXMiLCJmaW5kaW5ncyI6W3sic2V2ZXJpdHkiOiJtZWRpdW0iLCJjYXRlZ29yeSI6ImFwaS1jb250cmFjdCIsImZpbGUiOiJkb2NzL25vcm1hdGl2ZS9lbnRpdHktc291cmNlLWNvbmZpZ3VyYXRpb24vdjEvUkVBRE1FLm1kIiwiaWQiOiJmX2E0YTZhNWYzZTIyNGUxMDMiLCJsaW5lIjoxMjMsImFjdGlvbmFibGUiOnRydWUsImRpbWVuc2lvbiI6ImNvcnJlY3RuZXNzIn0seyJzZXZlcml0eSI6ImxvdyIsImNhdGVnb3J5IjoiZG9jLXN0eWxlIiwiZmlsZSI6ImRvY3MvQURScy8wMDc5LWJpbmQtZW50aXR5LWV4ZWN1dGlvbi10aHJvdWdoLW5hbWVkLXNvdXJjZXMubWQiLCJpZCI6ImZfYjI2Y2UzZDUyNmM5OTc0YSIsImxpbmUiOjI0NiwiYWN0aW9uYWJsZSI6dHJ1ZSwiZGltZW5zaW9uIjoic3R5bGUtY29udmVudGlvbnMifSx7InNldmVyaXR5IjoibG93IiwiY2F0ZWdvcnkiOiJkb2Mtc3R5bGUiLCJmaWxlIjoiZG9jcy9ub3JtYXRpdmUvZW50aXR5LXNvdXJjZS1jb25maWd1cmF0aW9uL3YxL1JFQURNRS5tZCIsImlkIjoiZl8zODA4MDhiNjc4NDUyZGJlIiwibGluZSI6NzcsImFjdGlvbmFibGUiOnRydWUsImRpbWVuc2lvbiI6InN0eWxlLWNvbnZlbnRpb25zIn0seyJzZXZlcml0eSI6ImxvdyIsImNhdGVnb3J5IjoiZG9jLXN0eWxlIiwiZmlsZSI6ImRvY3MvcHJvYmxlbXMvYWdlbnQtaW5mcmFzdHJ1Y3R1cmUubWQiLCJpZCI6ImZfNTE2N2RhZTZmNmI3NTIzYSIsImxpbmUiOjEyOSwiYWN0aW9uYWJsZSI6dHJ1ZSwiZGltZW5zaW9uIjoic3R5bGUtY29udmVudGlvbnMifSx7InNldmVyaXR5IjoibG93IiwiY2F0ZWdvcnkiOiJkb2Mtc3R5bGUiLCJmaWxlIjoiZG9jcy9BRFJzLzAwNzktYmluZC1lbnRpdHktZXhlY3V0aW9uLXRocm91Z2gtbmFtZWQtc291cmNlcy5tZCIsImlkIjoiZl85ZmRkODMzYzliZDM3NTEyIiwibGluZSI6NDU1LCJhY3Rpb25hYmxlIjp0cnVlLCJkaW1lbnNpb24iOiJzdHlsZS1jb252ZW50aW9ucyJ9LHsic2V2ZXJpdHkiOiJsb3ciLCJjYXRlZ29yeSI6Im1pc3NpbmctZGVwcmVjYXRpb24iLCJmaWxlIjoiZG9jcy9ub3JtYXRpdmUvZW50aXR5LXNvdXJjZS1jb25maWd1cmF0aW9uL3YxL1JFQURNRS5tZCIsImlkIjoiZl8xZDY1M2VmYWUyNDk3OTI0IiwiYWN0aW9uYWJsZSI6ZmFsc2UsImRpbWVuc2lvbiI6ImNyb3NzLXJlcG8tY29udHJhY3RzIn0seyJzZXZlcml0eSI6ImxvdyIsImNhdGVnb3J5IjoibWlzc2luZy12ZXJzaW9uLWJ1bXAiLCJmaWxlIjoiZG9jcy9ub3JtYXRpdmUvZW50aXR5LXNvdXJjZS1jb25maWd1cmF0aW9uL3YxL1JFQURNRS5tZCIsImlkIjoiZl84NWRhYTEyYjVkN2RlMjU4IiwiYWN0aW9uYWJsZSI6ZmFsc2UsImRpbWVuc2lvbiI6ImNyb3NzLXJlcG8tY29udHJhY3RzIn0seyJzZXZlcml0eSI6ImxvdyIsImNhdGVnb3J5IjoiYmFja3dhcmQtaW5jb21wYXRpYmxlIiwiZmlsZSI6ImRvY3Mvbm9ybWF0aXZlL2VudGl0eS1zb3VyY2UtY29uZmlndXJhdGlvbi92MS9SRUFETUUubWQiLCJpZCI6ImZfZjQyYWVlYWUyNjY0ZGUxYSIsImFjdGlvbmFibGUiOnRydWUsImRpbWVuc2lvbiI6ImNyb3NzLXJlcG8tY29udHJhY3RzIn1dfQ== -->

Review

Findings

Medium

  • [api-contract] docs/normative/entity-source-configuration/v1/README.md:123 — Repository-scope omission has conflicting resolution rules. This paragraph permits omitting repositories only for the origin provider's default connection, but the "Native sources and reserved names" section lets a reserved source select another same-provider connection and defaults its repository scope to the clone's path on that selected instance. For a GitHub origin with connections.enterprise: {kind: github, base_url: ...} and entity_sources.github: {connection: enterprise, query: ""}, one rule requires an explicit repositories list and the other supplies one, so implementations would disagree on validity.
    Remediation: Define one repository-defaulting rule for a reserved native source that overrides its connection, state the exception in the general source-validation rules, and add the case to the conformance requirements.

Low

  • [backward-incompatible] docs/normative/entity-source-configuration/v1/README.md — The legacy translation rules do not say how a tracker.github or tracker.gitlab mapping translates. These blocks carry only allowed_targets, and the translator creates legacy_tracker only when connection/polling settings exist, so the connection that receives the copied policy is unstated.
    Remediation: Define the translation target for tracker.github and tracker.gitlab and add a conformance case.
  • [missing-deprecation] docs/normative/entity-source-configuration/v1/README.md — tracker is declared deprecated but no removal criterion, target release, or minimum support window is given; the only exit is an undefined "coordinated entity-mode cutover".
  • [missing-version-bump] docs/normative/entity-source-configuration/v1/README.md — The config carries no version or capability marker, and config decoding is strict (unknown keys rejected), so older binaries fail with a generic unknown-field error when new keys are adopted. Consider a version/minimum-CLI rule or an explicit statement that this skew is accepted.
  • [doc-style] docs/ADRs/0079-bind-entity-execution-through-named-sources.md:246 — "Fullsend" is capitalized mid-sentence (lines 246, 247, 275, 330, 339, 348, 373); docs/contributing/documentation.md requires lowercase "fullsend" in running prose.
  • [doc-style] docs/normative/entity-source-configuration/v1/README.md:77 — Same product-name casing issue at lines 77, 142, 663, 692.
  • [doc-style] docs/problems/agent-infrastructure.md:129 — Same product-name casing issue ("in Fullsend, execution in CI").
  • [doc-style] docs/ADRs/0079-bind-entity-execution-through-named-sources.md:455 — Lines 455-459 are unwrapped single lines up to 147 characters; docs/contributing/documentation.md asks for wrapping at about 80 columns.

Labels: Documentation-only ADR and normative spec PR


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

fullsend-ai-review[bot]

This comment was marked as outdated.

@codecov

codecov Bot commented Nov 8, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Require same-named connection defaults and reserved source connections, and
clarify when the origin repository path is inherited. Bind credentials to
trusted endpoints, specify GitLab closed-state expansion, and resolve
documentation and migration review findings.

Signed-off-by: Barak Korren <bkorren@redhat.com>
Assisted-by: Codex
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 9:44 PM UTC · Completed 9:52 PM UTC

Commit: 7fd1769 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $2.37

fullsend-ai-review[bot]

This comment was marked as outdated.

Signed-off-by: Barak Korren <bkorren@redhat.com>
Assisted-by: Codex
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 10:23 PM UTC · Completed 10:32 PM UTC

Commit: 31c0a9f · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.60

@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review November 8, 2026 22:32

Superseded by updated review

@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review November 8, 2026 22:32

Superseded by updated review

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Nov 8, 2026

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — 31c0a9fc Deployed Nov 8, 2026 by github-actions[bot]
dev — 31c0a9fc Deployed Nov 8, 2026 by ifireball via behaviour #19284
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/docs User-facing documentation documentation ready-for-merge All reviewers approved — ready to merge risk/moderate PR risk: moderate type/adr

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant