[ifireball]

Summary

Record ADR 0149's entity-source discovery query contract. fullsend poll will
combine admissible harness queries into one scope-guarded logical candidate
search and route candidates locally. A bound run will recheck source-query
membership for both event-backed and eventless cycles before sandbox admission.

Related Issues

Advances #8421; entity-first implementation is tracked in #8418. No issue is
closed by this documentation PR.

Changes

• Require sound query combination, local membership evaluation, and routing
  to every matching harness.
• Keep candidate discovery separate from final CEL evaluation, with retry or
  rediscovery for incomplete search and query evidence.
• Require a trusted search scope guard and coverage across pagination,
  provider caps, index lag, and concurrent changes.
• Preserve ADR 0098 and Authorization Contract v1's full actor-history,
  current-role, and audit requirements for CEL; require a new major contract
  for the source-query admission gate before implementation.
• Add short Status annotations to accepted ADRs 0098 and 0144, and update the
  architecture and agent-architecture living documents.

Testing

• CI=1 make lint passed on the staged documentation changes.
• git diff --cached --check passed before committing.
• Documentation only; no production logic changed.

Checklist

• PR title follows Conventional Commits.
• Commit has the required DCO sign-off.
• I wrote this contribution myself and can explain all changes in it.

[qodo-code-review]

PR Summary by Qodo

Document coalesced entity-source discovery and authorization rules

📝 Documentation 🕐 40+ Minutes

AI Description

• Require scope-guarded candidate searches and local routing to every matching harness.
• Require bound runs to recheck source-query membership and CEL before sandbox admission.
• Define selective evidence, bounded actor-role reuse, and retry requirements for future
 entity-source execution.

Diagram

graph TD
  Q["Harness queries"] --> S["Guarded search"] --> R["Local routing"] --> B["Bound run"] --> A["Actor gate"] --> D{"Query and CEL"}
  D -->|true| X["Sandbox cycle"]
  D -->|unknown| T["Retry discovery"] --> S

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Search separately for each harness

• ➕ Allows more provider-native query operators without combining them.
• ➖ Provider calls scale with harness count.
• ➖ Still requires deduplication, coverage guarantees, and a current admission check.

Recommendation: Keep the coalesced, locally rechecked design: it shares discovery work without treating provider search results as authorization or current membership evidence. Its restriction to queries that adapters can combine and reproduce locally is a deliberate trade-off; retain the specified versioned protocol and authorization-contract prerequisites before implementation.

Files changed (13) +1245 / -18

Documentation (13) +1245 / -18

config.tsExpose normative specifications in the docs sidebar +5/-0

Expose normative specifications in the docs sidebar

• Adds a navigation group for versioned normative specifications so readers can find the authorization contracts.

docs/.vitepress/config.ts

0063-polling-based-work-discovery.mdClarify retry requirements alongside legacy polling +5/-0

Clarify retry requirements alongside legacy polling

• Points to ADR 0147's retry or proven-rediscovery requirement for provisional entity-source handoffs while preserving the legacy event-reconstruction checkpoint rule.

docs/ADRs/0063-polling-based-work-discovery.md

0098-entity-first-harness-evaluation.mdMark entity-evaluation guarantees superseded by newer ADRs +16/-1

Mark entity-evaluation guarantees superseded by newer ADRs

• Identifies the selective-acquisition and bounded-role-reuse decisions that supersede portions of the earlier design. Records ADR 0149's mandatory combined search, local routing, and source-query membership gate.

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

0144-reuse-poll-and-entity-bound-run-processes.mdRelate process reuse to updated entity checks +11/-0

Relate process reuse to updated entity checks

• Clarifies which due-check and authorization requirements are superseded by ADRs 0147 and 0148. Links the lifecycle design to ADR 0149's discovery strategy and pre-sandbox query check.

docs/ADRs/0144-reuse-poll-and-entity-bound-run-processes.md

0147-evaluate-entity-cel-over-selectively-acquired-data.mdAdopt selective acquisition for entity CEL +164/-0

Adopt selective acquisition for entity CEL

• Defines progressive, decision-relevant acquisition with explicit UNKNOWN outcomes, coverage evidence, actor gates, and retryable provisional handoffs. Replaces full-history evaluation and audit requirements for the future entity-source path.

docs/ADRs/0147-evaluate-entity-cel-over-selectively-acquired-data.md

0148-reuse-verified-actor-roles-for-entity-cel.mdAdopt bounded actor-role reuse for entity checks +125/-0

Adopt bounded actor-role reuse for entity checks

• Allows scoped, provider-verified actor verdicts to be reused for entity CEL within an absolute maximum age of five minutes. Requires invalidation, evidence-age auditing, and rechecks for false results dependent on cached authorization.

docs/ADRs/0148-reuse-verified-actor-roles-for-entity-cel.md

0149-coalesce-entity-source-discovery-queries.mdAdopt combined discovery and local source-query routing +148/-0

Adopt combined discovery and local source-query routing

• Requires one scope-guarded logical candidate search per source scope and local membership checks for every relevant harness. Makes current query membership an admission condition for event-backed and eventless bound runs, with coverage, retry, and versioned-contract prerequisites.

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

architecture.mdReflect target discovery and selective authorization architecture +45/-15

Reflect target discovery and selective authorization architecture

• Adds the combined-search and bound-run recheck design to the architecture overview. Replaces full-history assumptions with selective acquisition, bounded role reuse, unresolved-result handling, and decision-focused audit evidence.

docs/architecture.md

README.mdIdentify v1 as the historical authorization contract +9/-1

Identify v1 as the historical authorization contract

• Links to v2 and explains which future entity-evaluation guarantees it supersedes. Clarifies that existing event-backed dispatch continues under v1 until migration.

docs/normative/authorization/v1/README.md

README.mdSpecify authorization for selective entity evaluation +703/-0

Specify authorization for selective entity evaluation

• Introduces a versioned contract for decision-relevant actor gating, partial-data semantics, bounded actor-verdict reuse, audit evidence, and retryable handoffs. Preserves separate event-actor and model-bound admission rules; ADR 0149 calls for a later major version to specify its source-query admission gate.

docs/normative/authorization/v2/README.md

agent-architecture.mdConnect agent architecture to entity discovery decisions +8/-0

Connect agent architecture to entity discovery decisions

• References progressive entity checks, bounded actor-role sharing, combined candidate searches, and bound-run query rechecks.

docs/problems/agent-architecture.md

agent-infrastructure.mdQualify actor-role reuse in repeated checks +1/-1

Qualify actor-role reuse in repeated checks

• Notes that reused host processes may share verified actor roles only within ADR 0148's bounded lifetime.

docs/problems/agent-infrastructure.md

operational-observability.mdLink entity-decision audits to bounded evidence +5/-0

Link entity-decision audits to bounded evidence

• Connects entity-trigger tracing to bounded provenance and coverage evidence, including the age of shared actor-role results.

docs/problems/operational-observability.md

[qodo-code-review]

Code Review by Qodo

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

1. Planned behavior lacks a tracked issue ✓ Resolved

Description

ADR 0149 describes harness entity-source discovery as a target design without using the required
planned-feature callout or linking an issue. Readers of the ADR can therefore mistake an
unimplemented discovery contract for an actionable current capability, and the same omission appears
in the newly documented architecture direction.

Code

docs/ADRs/0149-coalesce-entity-source-discovery-queries.md[R39-41]

+receive each result. The current [`fullsend poll` command](https://github.com/fullsend-ai/fullsend/blob/35c8bf8dc98dd91abc582bfd22fab9e5ce905d47/internal/cli/poll.go#L41-L64)
+still uses event-reconstructing input drivers; harness entity-source discovery
+is a target design.

Evidence

The new ADR explicitly says entity-source discovery is a target design, which identifies behavior
that is not yet implemented, but the surrounding text is not a > **Planned:** callout and contains
no issue link. The checklist requires every mention of a not-yet-implemented feature to use that
format and avoid presenting it as current functionality.

docs/ADRs/0149-coalesce-entity-source-discovery-queries.md[39-41]
Skill: writing-user-docs

Agent prompt

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

## Issue description
The ADR describes entity-source discovery as a target design, but it does not use the required `> **Planned:**` callout or link to the issue tracking the feature.

## Fix Focus Areas
- docs/ADRs/0149-coalesce-entity-source-discovery-queries.md[39-41]

## Recommended Fix
Rewrite the not-yet-implemented feature reference as a `> **Planned:**` blockquote and include a link to the relevant issue; apply the same format to any other newly added planned-feature references in the affected documentation.

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

---

2. Entity architecture prose is rewritten 📜 Skill insight ⚙ Maintainability

Description

docs/architecture.md replaces the existing entity-first authorization and acquisition narrative,
including its full-history guarantees and open question, with a new selective-acquisition design
rather than adding a surgical annotation. The change alters the established architecture description
across the entity-dispatch section, so later readers lose a concise historical record of what was
decided and what was superseded.

Code

docs/architecture.md[R472-475]

+  cycle. The platform classifies action-indicating categories, but acquires
+  only entity data that can affect each harness's CEL predicate. Classified
+  action signals require provider-verified actor roles under that harness's
+  stage policy; service-clock state may be evaluated without unrelated

Evidence

The diff removes the prior full-history and closed-superset description and replaces it with a new
selective-acquisition narrative in the same architecture section. The checklist permits short
supersession notes but prohibits substantive rewrites of living-document sections.

docs/architecture.md[472-502]
Skill: writing-adrs

Agent prompt

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

## Issue description
The entity-first section of `docs/architecture.md` substantially rewrites existing architecture prose instead of making a minimal living-document update. Preserve the existing description and annotate superseded guarantees with concise links to the applicable ADRs.

## Fix Focus Areas
- docs/architecture.md[472-487]

## Recommended Fix
Restore the existing entity-first architecture narrative and retain only surgical additions identifying which guarantees ADRs 0147 and 0148 supersede. Keep the remaining open question intact or append a short note linking to ADR 0149 while identifying the specific schema and adapter details that remain unresolved.

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

Dismiss ↗ | View ↗

---

3. Accepted ADR edits go unmentioned ⊘ Outdated

Description

The PR description names ADR 0149 but omits the accepted ADRs 0063, 0098, and 0144 that this change
modifies. Because those accepted records receive new cross-references and supersession notes, the PR
summary does not identify the affected decisions or explain the edits.

Code

docs/ADRs/0098-entity-first-harness-evaluation.md[R46-50]

+[ADR 0147](0147-evaluate-entity-cel-over-selectively-acquired-data.md)
+partially supersedes the pre-CEL full-history enumeration, permission
+resolution for every history actor, and audit-roster requirements below.
+[ADR 0148](0148-reuse-verified-actor-roles-for-entity-cel.md) separately permits
+bounded role reuse across entity-CEL checks and partially supersedes the

Evidence

The modified ADR files are accepted records and the diff adds new ADR references to them, but the
supplied PR description discusses ADR 0149 and the stacked issue without explicitly naming ADRs
0063, 0098, or 0144. This fails the requirement to call out edits to accepted ADRs in the PR
description.

Rule 1062059: Call out edits to accepted ADRs in PR descriptions
docs/ADRs/0098-entity-first-harness-evaluation.md[46-50]
docs/ADRs/0144-reuse-poll-and-entity-bound-run-processes.md[32-41]
docs/ADRs/0063-polling-based-work-discovery.md[41-44]

Agent prompt

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

## Issue description
The PR description does not explicitly identify accepted ADRs 0063, 0098, and 0144 even though the PR modifies them with cross-references and supersession notes.

## Fix Focus Areas
- docs/ADRs/0098-entity-first-harness-evaluation.md[46-50]
- docs/ADRs/0144-reuse-poll-and-entity-bound-run-processes.md[32-41]
- docs/ADRs/0063-polling-based-work-discovery.md[41-44]

## Recommended Fix
Update the PR description with each modified accepted ADR identifier or filename and a brief summary of the related cross-reference or supersession annotation.

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

---

Context sources

❌ Tickets: failed to load — Ticket collection could not establish complete evidence

✅ Compliance rules (platform): 95 rules

✅ Skills: 5 invoked

  writing-user-docs

  writing-adrs

  check-patch-coverage

  cutting-releases

  adr-corner

✅ Cross-repo context — repo relationships

  Explored: repo: fullsend-ai/agents (sha: 797386c1) — View relationship

Review mode: Auto: ⚖️ Balanced: Normative authorization and architecture changes have broad contract and security implications.

Tip of the day

💡 Did you know, you can ask Qodo to dismiss a finding you disagree with, with your reason on record

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 10:19 AM UTC · Ended 10:37 AM UTC

Commit: 3d4a06f · View workflow run →

This review was superseded by a newer commit. Check the current pull request HEAD's review status before merging.

[github-actions]

Site preview

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

Commit: 87760a228dff998c04f9bc23c421af6d9f810ced

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

<!-- fullsend:risk-assessment -->
Risk Assessment: moderate (2/5)

Details

Documentation-only ADR change with no code or protected paths, elevated to moderate risk by high commit churn, author contention, and coupling on core architectural documents.

Previous run

<!-- fullsend:risk-assessment -->
Risk Assessment: moderate (2/5)

Details

Documentation-only ADR change with no code or protected paths, elevated to moderate risk by high commit churn, author contention, and coupling on core architectural documents.

Previous run (2)

<!-- fullsend:risk-assessment -->
Risk Assessment: moderate (2/5)

Details

Large documentation change with no code or protected paths, elevated to moderate by high commit churn and multi-author contention on central architectural documents.

[fullsend-ai-review]

Looks good to me

Earlier findings

• docs/architecture.md:476, doc-style — resolved: the paragraph is re-wrapped as a bullet at docs/architecture.md:473-481 with prose lines within the wrapping limit.
• docs/ADRs/0149-coalesce-entity-source-discovery-queries.md:36, doc-style — resolved: the Context paragraph is re-wrapped at lines 36-43; only the permalink URL line exceeds 80 columns.
• docs/architecture.md:473, pattern-inconsistency — resolved: the **Planned:** prefix is replaced by the (target state): bullet form used in the surrounding section.
• docs/ADRs/0149-coalesce-entity-source-discovery-queries.md:36, pattern-inconsistency — resolved: the **Planned:** prefix is removed and the paragraph now starts with the plain statement.

Previous run

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

Review

Findings

Low

• [doc-style] docs/architecture.md:476 — Line is 94 characters, over the ~80-column prose wrapping rule; the ADR 0149 link fits on its own line, so the long-link exemption does not apply.
  Remediation: Wrap before the ADR 0149 link.
• [doc-style] docs/ADRs/0149-coalesce-entity-source-discovery-queries.md:36 — Line is 106 characters, over the ~80-column wrapping rule; the Implement ADR 0098 entity-first harness evaluation #8418 link fits on its own line.
  Remediation: Wrap the paragraph before the Implement ADR 0098 entity-first harness evaluation #8418 link (the poll.go permalink on line 38 is exempt).
• [pattern-inconsistency] docs/architecture.md:473 — Coordinator-section items are bullets, and not-yet-built behavior uses a "(target state)" label; the new entry is a standalone **Planned:** paragraph. Optional nit; **Planned:** is used elsewhere in the repo.
• [pattern-inconsistency] docs/ADRs/0149-coalesce-entity-source-discovery-queries.md:36 — Inline **Planned:** marker in Context differs from sibling ADRs. Optional nit; the repo uses the marker for unbuilt behavior.

---

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

Review

Reason: stale-head

The review agent reviewed commit 3d4a06f6a9e52eeb59812e37f336a34201d5f640 but the PR HEAD is now ccdd0efbe1db9fb142c9e2628b1d0ea81aa34fd0. This review was discarded to avoid approving unreviewed code.

[fullsend-ai-review]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:40 AM UTC · Completed 10:58 AM UTC

Commit: ccdd0ef · View workflow run →

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

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Ended 9:27 PM UTC

Commit: 97cfccd · View workflow run →

This review was superseded by a newer commit. Check the current pull request HEAD's review status before merging.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:29 PM UTC · Completed 9:37 PM UTC

Commit: 87760a2 · View workflow run →

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

Superseded by updated review