Repository navigation
Description
Problem
#102884 landed typed, directed report links (phase 1 of #102776). Scouts and the pipeline can now write depends_on, part_of, follow_up_of, duplicate_of and recurrence_of edges between reports. Nothing reads them yet.
- Research still starts every report from scratch. A report marked
follow_up_ofan earlier one re-derives the earlier investigation and often misses its PR. - Auto-start still opens a PR for a report that is
duplicate_ofa report with a PR in flight, and for a report whosedepends_ontarget has not produced a branch to base on.maybe_autostart_implementation_taskinproducts/signals/backend/auto_start.pygates onalready_addressed, actionability and priority only. - Completion is per report. A
part_ofparent never resolves, becauseapply_report_completioninproducts/signals/backend/pull_requests.pyonly looks at the report's own PRs. - Research's in-flight check records a sibling's open PR as
already_addressed: trueand nothing else, so the inbox cannot say which report the work moved to. - The check-failure re-surface (
report_check_execution.py,source_product="signals_check") still relies on grouping's untypedrelated_torow, so a fresh report for a failed check carries no verdict and nofollow_up_ofedge. - The inbox shows a report's outgoing links in the work log only. A report that other reports point at shows nothing.
What phase 1 actually shipped, and what it changes for this phase
The parent spec assumed a mirrored related_to row with a direction on each side. Phase 1 chose a separate report_link artefact instead: one directed row on the source report, no mirror, content is a JSON string with kind, report_id and an optional reason (ReportLink in artefact_schemas.py; ReportLinkKind in enums.py). Legacy related_to rows are untouched, so recurrence_of exists in both vocabularies for now.
Consequences for phase 2:
- Outgoing reads are cheap. The auto-start gate, the PR base and the research context all walk edges written on the report itself: filter
report_linkartefacts byreport_idand parse. - Incoming reads need a scan. The parent roll-up and the "Linked reports" rail want every report that points at this one.
contentis aTextField, so that isfilter(team_id, type="report_link", content__contains=<report uuid>)then parse and checkreport_idandkind. Links are rare and team-scoped, so a scan is fine to start. If it shows up in query timings, the follow-up is a materialised target column or a JSON index, not a mirror row. Put the read in one helper onSignalReportArtefactnext to_report_link_reaches, so every reader shares it. - The parent spec's mirror-row sections are superseded by this issue.
Proposal
1. One read module
Add outgoing and incoming link readers on SignalReportArtefact (or a sibling module next to artefact_schemas.py), returning parsed ReportLink rows with the source and target report ids. Both readers are team-scoped and tolerate rows that no longer parse, the same way _report_link_reaches does. Everything below calls these two functions.
Add a duplicate_of root resolver: follow duplicate_of edges from a report until a report with no outgoing duplicate_of edge, bounded by the existing graph budgets. Every duplicate_of reader below acts on the root.
2. Research context for linked reports
In products/signals/backend/temporal/agentic/report.py, _load_resolved_report_context reads related_to rows to hand a recurrence's resolved source to the research prompt. Extend it:
- Read outgoing
report_linkrows of kindfollow_up_of,depends_onandpart_of. - For each target, load title, summary, the latest
signal_findingartefacts and the attached PR URLs with their state (SignalReportPullRequestrows throughfetch_implementation_prs_for_reports). - Put them in the research prompt under a heading per kind, with the link
reasonwhere one exists. - The research protocol in
report_generation/research.pysays: afollow_up_ofreport starts from the linked report's PR and findings, and names that PR in its own finding. Adepends_onreport scopes itself to what the dependency does not cover.
Keep the related_to recurrence read as it is.
3. Research writes duplicate_of
The in-flight check in research.py sets already_addressed when it finds an open PR covering the same fix. When that PR is attached to another report on the same team (a SignalReportPullRequest row for the URL, joined to its report), also write a duplicate_of link to that report with the PR URL as the reason. Resolve to the root first. The already_addressed field keeps its meaning; the link is additive.
Attribution follows the pipeline's existing ArtefactAttribution for research artefacts.
4. Auto-start gate
In maybe_autostart_implementation_task, after the existing skips and before the task is created, add three skips:
| Skip reason | Rule |
|---|---|
duplicate_of |
The report has an outgoing duplicate_of edge, and the root has a PR in open or merged state, or is resolved. |
blocked_by_dependency |
Any outgoing depends_on target has no PR in open or merged state. |
plan_parent |
The report has one or more incoming part_of edges. A parent is the plan and never gets its own run. |
Each skip:
- returns
AutostartOutcome(status="blocked", reason=...)as today, - writes a new
autostart_skipartefact on the report (skip_reason, the linked report id where there is one, and a short human-readable line), so the work log and the detail view can say why nothing started, - fires one analytics event,
signals_autostart_skipped, withskip_reason, so the share of reports held by each gate is readable.
The gate applies to the automatic path only. Pressing Implement in the inbox goes through the tasks API and stays available, so a person can always override a gate.
Nothing in this phase re-evaluates a blocked report when its dependency's PR opens. Sequencing (layer N+1 starts when layer N's PR is open) is phase 3. Until then a blocked child starts on the next pipeline evaluation of that report, or by hand.
This closes #90186 for the linked case. Two unlinked reports that name the same fix are still the fan-out problem in #90190.
5. PR base from the dependency
When the depends_on gate is met, _create_implementation_task_if_absent receives the dependency's PR head branch as base_branch instead of the team's configured base. Read the head ref from GitHub for the dependency's open PR (GitHubIntegrationBase, the PR URL from SignalReportPullRequest). When the dependency PR is already merged, keep the team's base. When the head ref cannot be read, skip with blocked_by_dependency and say so in the artefact, rather than opening a PR against the wrong base.
The child keeps its own pre-generated self_driving_head_branch, so the run-to-PR join in products/tasks/backend/webhooks.py and find_signal_implementation_run are unchanged. The task description names the dependency's PR and head branch so the agent knows it is stacking. A GitHub-side stack link is phase 3.
6. Completion roll-up
In apply_report_completion, after the report's own state is applied, walk its outgoing part_of edges and re-evaluate each parent:
- every child
resolved(orresolvedandsuppressedmixed with at least oneresolved) resolves the parent, - every child
suppressedsuppresses the parent, - otherwise the parent is untouched.
Children keep the current per-report rule. The roll-up also runs when a child is resolved or dismissed by hand through inbox-reports-set-state, so a parent does not wait for a PR event that never comes. A parent with a pending replacement (pending_replacement) is skipped like any other report.
7. Failed checks write follow_up_of
When a metric_threshold check fails on a resolved report and report_check_execution.py emits the signals_check signal, the fresh report that grouping creates gets a follow_up_of link to the origin report with the verdict as the reason. Grouping keeps writing related_to for the recurrence read until that read moves to recurrence_of; the two rows say different things (this recurred; this follows that up because a check failed).
8. Inbox: linked reports rail
The detail view gets a "Linked reports" section that lists both directions, grouped by kind, each row with the other report's title, its status pill and its PR state where one exists. Outgoing rows read "Depends on ...", incoming rows read the inverse ("... depends on this report"), using REPORT_LINK_KIND_LABELS. The autostart_skip artefact renders in the work log with the skip reason in plain words.
The collapsed list view (children under their parent, duplicates under their root) is phase 3.
9. Analytics
signals_report_linkedwithkind, the writer identity and whether the link was plan-authored. The parent spec listed this for phase 1; it did not ship, so it lands here.signals_autostart_skippedwithskip_reason(duplicate_of,blocked_by_dependency,plan_parent, plus the existing string reasons).
Carried over from #102884 review
Three review threads were left open on the merged PR. They are small and fit either this PR or a preceding one:
- Document the scout
linkssurface: thescout-edit-reporttool description and the report contract in theauthoring-scoutsskill. - A supported way to remove a link. Proposed: a
remove_linkslist onscout-edit-report, deleting only rows the same scout wrote, with anoteartefact recording the removal. - Reject a link whose source report is deleted, in
validate_report_link.
Tests
- Outgoing and incoming readers return the same edge from either end; a row that does not parse is skipped; a
duplicate_ofchain resolves to its root and a bounded budget stops a long chain. - Auto-start does not start a report that is
duplicate_ofa root with an open PR; does not start a child whosedepends_ontarget has no open or merged PR; starts it once that PR opens and passes the dependency's head branch asbase_branch; does not start a report with incomingpart_ofedges. Each skip writes oneautostart_skipartefact and onesignals_autostart_skippedevent. - A parent resolves when the last child resolves, is suppressed when all children are suppressed, and is untouched while any child is open, both from a PR webhook and from a manual set-state.
- Research on a
follow_up_ofreport gets the linked report's title, summary, findings and PR URL in its prompt (prompt snapshot). Research that finds a sibling report's open PR writesduplicate_ofto that report's root and setsalready_addressed. - A failed
metric_thresholdcheck on a resolved report produces a fresh report with afollow_up_oflink whosereasonis the verdict. - Detail view: a report shows incoming and outgoing links grouped by kind with the other report's status; an
autostart_skipartefact renders its reason.
Out of scope
- Sequencing: re-evaluating a blocked child when its dependency's PR opens (phase 3).
layerson the research output, child report creation and the GitHub Stacks API link (phase 3).- Supersession over a
depends_onsubgraph (phase 3). - The collapsed inbox list (phase 3).
- Restacking a child after its dependency's branch moves.
- Migrating
related_torows torecurrence_oflinks. - The one-issue-many-reports fan-out itself (fix(signals): the enablement backfill fans the five newest issues into separate reports and PRs within minutes #90189, Duplicate inbox reports and competing PRs for one fix (tracking) #90190).
Pointers
- Link primitive as landed:
ReportLinkandMAX_REPORT_LINKS_PER_WRITEinproducts/signals/backend/artefact_schemas.py;ReportLinkKindandREPORT_LINK_KIND_LABELSinproducts/signals/backend/enums.py;validate_report_link,validated_report_link_writeand_report_link_reachesonSignalReportArtefactinproducts/signals/backend/models.py; scout write path inproducts/signals/backend/scout_harness/tools/report.py; policy indocs/internal/signals-pr-lifecycle.md. - Recurrence context:
_load_resolved_report_contextinproducts/signals/backend/temporal/agentic/report.py; therelated_towriter inproducts/signals/backend/temporal/grouping.py. - Research protocol and in-flight check:
ReportPresentationOutput, the "Work already in flight" section andalready_addressedinproducts/signals/backend/report_generation/research.py. - Auto-start:
maybe_autostart_implementation_task,_create_implementation_task_if_absent(base_branch=...),_build_autostart_task_description,_generate_self_driving_head_branchinproducts/signals/backend/auto_start.py;AutostartOutcome. - Completion and PRs:
apply_report_completionandcompletion_stateinproducts/signals/backend/pull_requests.py;SignalReportPullRequestinmodels.py;fetch_implementation_prs_for_reportsinproducts/signals/backend/implementation_pr.py;_apply_pr_report_stateinproducts/signals/backend/report_assignments.py. - Check failure re-surface:
products/signals/backend/report_check_execution.pyaround theSignalSourceProduct.SIGNALS_CHECKemit; "Report checks" inproducts/signals/ARCHITECTURE.md. - Run-to-PR binding:
find_signal_implementation_runinproducts/tasks/backend/facade/api.py;products/tasks/backend/webhooks.py. - Frontend:
ArtefactLogList.tsxandartefactTypes.tsinproducts/signals/frontend/inbox/components/detail/. - Parent spec and decisions: feat(signals): typed report links, and a report per PR for stacked work #102776. Phase 1: feat(signals): add typed, directed links between inbox reports #102884.
Landing plan
One PR is fine if it stays reviewable. If it splits, this order keeps each step useful on its own:
- Read helpers, root resolver, research context,
duplicate_offrom the in-flight check,signals_report_linked. - Auto-start gate,
autostart_skipartefact, PR base from the dependency,signals_autostart_skipped. - Completion roll-up,
follow_up_offrom failed checks, the linked reports rail.
Activity
feat(signals): act on typed report links in research, auto-start and …
feat(signals): act on typed report links in research, auto-start and …