Document dual-model (Application + ComponentGroup) completeness requirement in AGENTS.md

[fullsend-ai-retro]

What happened

PR #1543 added distributed tracing with timing span emission across integration-service controllers. The fullsend-ai-review bot ran 10 iterations, gemini-code-assist posted 5 suggestions, and CodeQL flagged one issue. Despite this automated coverage, the most critical bugs were found only by human reviewer kasemAlem on 2026-05-18: two missing emission paths in the Application model flow of buildpipeline_adapter.go. Specifically:

1. The EnsureSnapshotExists (ComponentGroup flow) had emission but EnsureSnapshotExistsApplication did not.
2. An early return in EnsureSnapshotExistsApplication when the snapshot annotation already exists skipped timing span emission entirely on restarts/requeues.

These were domain-specific completeness bugs that required knowledge of the dual-model architecture. No automated reviewer flagged them because the AGENTS.md file does not document the dual-model pattern as a completeness requirement.

What could go better

The repo's AGENTS.md documents the adapter pattern, controller structure, and development guidelines, but does not mention that integration-service maintains two parallel flows — ComponentGroup (new) and Application (legacy, planned for deprecation) — and that feature implementations in controllers must cover both. This context gap is the root cause of the automated review miss.

The dual-model pattern is visible in code (e.g., NewAdapter() vs NewAdapterWithApplication() in snapshot_adapter.go, TODO comments about deprecation) but is never stated as a completeness requirement. Human reviewers like kasemAlem know this from experience; automated reviewers need it spelled out.

Confidence: High. The evidence is clear — kasemAlem's comment explicitly says "if you want to continue with implementing this distributed tracing feature you should take care of both flows" and points to two specific locations. This is a repeatable pattern: any future cross-cutting feature (metrics, logging changes, new annotations) faces the same risk of incomplete dual-model coverage.

Proposed change

Add a "Dual-Model Architecture" section to AGENTS.md (which serves as the repo's CLAUDE.md) under the Architecture heading. The section should:

1. Explain that integration-service currently supports two parallel flows: ComponentGroup model (new) and Application model (legacy, planned for deprecation per README.md).
2. State explicitly that any feature touching controllers/adapters must be implemented and tested for both flows until the Application model is fully deprecated.
3. List the key dual-path locations: snapshot_adapter.go (NewAdapter vs NewAdapterWithApplication), buildpipeline_adapter.go (EnsureSnapshotExists vs EnsureSnapshotExistsApplication), and related test files.
4. Note that TODO comments marked "remove when we deprecate old application model" indicate Application-model code paths that must be maintained.

Example addition after the "Adapter Pattern" subsection:

### Dual-Model Architecture

The service supports two parallel resource flows: **ComponentGroup** (new model) and **Application** (legacy, planned for deprecation). Controllers and adapters implement both flows side-by-side (e.g., `EnsureSnapshotExists` vs `EnsureSnapshotExistsApplication`). Any cross-cutting feature — tracing, metrics, annotations, error handling — must cover both flows until the Application model is fully removed. Look for `TODO: remove when we deprecate old application model` comments to identify Application-model code paths.

Validation criteria

1. The next cross-cutting feature PR to integration-service (touching 2+ controllers) should have automated review findings that reference dual-model completeness, or should not require a human to catch missing coverage in one of the two flows.
2. The AGENTS.md file contains an explicit mention of both ComponentGroup and Application flows as a completeness requirement.
3. Measurable over the next 3 PRs that touch controller adapters: zero human-only catches of missing dual-model coverage that automated reviewers should have flagged.

---

Generated by retro agent from #1543

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 9:12 PM UTC · Completed 9:14 PM UTC
Commit: ec21706 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Category: Documentation | Severity: Medium

This issue requests adding documentation for the dual-model architecture (Application + ComponentGroup flows) to AGENTS.md so that automated reviewers can enforce completeness across both flows.

Assessment

The dual-model pattern is confirmed in the codebase across 9 files spanning buildpipeline, snapshot, and statusreport controllers. Key dual-path methods include EnsureSnapshotExists vs EnsureSnapshotExistsApplication and NewAdapter vs NewAdapterWithApplication. The issue provides a clear, well-scoped proposed change with example markdown.

The originating PR (#1543) is already merged, confirming the real-world impact: missing tracing emission in the Application flow was caught only by a human reviewer.

Recommended Fix

Add a "Dual-Model Architecture" subsection under the Architecture heading in AGENTS.md, after "Adapter Pattern". The proposed text in the issue body is a good starting point.

Proposed Test Case

Verify after the change:
1. AGENTS.md contains a section mentioning both "ComponentGroup" and
   "Application" flows as a completeness requirement
2. The section references key dual-path files:
   - buildpipeline_adapter.go
   - snapshot_adapter.go
   - statusreport_adapter.go
3. The TODO marker pattern described in the docs
   ("TODO.*deprecate old application model") matches actual
   code occurrences in the repository

This is a good first issue — it is a focused, self-contained documentation change with a clear example provided.

---

Labels: Documentation-only change to AGENTS.md; also a good candidate for newcomer contributors given its focused scope.

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 9:17 PM UTC · Completed 9:20 PM UTC
Commit: ec21706 · View workflow run →