Skip to content

feat(signals): act on typed report links in research, auto-start and completion #103661

Closed

Description

@andrewm4894

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_of an earlier one re-derives the earlier investigation and often misses its PR.
  • Auto-start still opens a PR for a report that is duplicate_of a report with a PR in flight, and for a report whose depends_on target has not produced a branch to base on. maybe_autostart_implementation_task in products/signals/backend/auto_start.py gates on already_addressed, actionability and priority only.
  • Completion is per report. A part_of parent never resolves, because apply_report_completion in products/signals/backend/pull_requests.py only looks at the report's own PRs.
  • Research's in-flight check records a sibling's open PR as already_addressed: true and 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 untyped related_to row, so a fresh report for a failed check carries no verdict and no follow_up_of edge.
  • 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_link artefacts by report_id and parse.
  • Incoming reads need a scan. The parent roll-up and the "Linked reports" rail want every report that points at this one. content is a TextField, so that is filter(team_id, type="report_link", content__contains=<report uuid>) then parse and check report_id and kind. 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 on SignalReportArtefact next 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_link rows of kind follow_up_of, depends_on and part_of.
  • For each target, load title, summary, the latest signal_finding artefacts and the attached PR URLs with their state (SignalReportPullRequest rows through fetch_implementation_prs_for_reports).
  • Put them in the research prompt under a heading per kind, with the link reason where one exists.
  • The research protocol in report_generation/research.py says: a follow_up_of report starts from the linked report's PR and findings, and names that PR in its own finding. A depends_on report 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_skip artefact 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, with skip_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 (or resolved and suppressed mixed with at least one resolved) resolves the parent,
  • every child suppressed suppresses 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_linked with kind, 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_skipped with skip_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 links surface: the scout-edit-report tool description and the report contract in the authoring-scouts skill.
  • A supported way to remove a link. Proposed: a remove_links list on scout-edit-report, deleting only rows the same scout wrote, with a note artefact 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_of chain resolves to its root and a bounded budget stops a long chain.
  • Auto-start does not start a report that is duplicate_of a root with an open PR; does not start a child whose depends_on target has no open or merged PR; starts it once that PR opens and passes the dependency's head branch as base_branch; does not start a report with incoming part_of edges. Each skip writes one autostart_skip artefact and one signals_autostart_skipped event.
  • 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_of report 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 writes duplicate_of to that report's root and sets already_addressed.
  • A failed metric_threshold check on a resolved report produces a fresh report with a follow_up_of link whose reason is the verdict.
  • Detail view: a report shows incoming and outgoing links grouped by kind with the other report's status; an autostart_skip artefact renders its reason.

Out of scope

Pointers

  • Link primitive as landed: ReportLink and MAX_REPORT_LINKS_PER_WRITE in products/signals/backend/artefact_schemas.py; ReportLinkKind and REPORT_LINK_KIND_LABELS in products/signals/backend/enums.py; validate_report_link, validated_report_link_write and _report_link_reaches on SignalReportArtefact in products/signals/backend/models.py; scout write path in products/signals/backend/scout_harness/tools/report.py; policy in docs/internal/signals-pr-lifecycle.md.
  • Recurrence context: _load_resolved_report_context in products/signals/backend/temporal/agentic/report.py; the related_to writer in products/signals/backend/temporal/grouping.py.
  • Research protocol and in-flight check: ReportPresentationOutput, the "Work already in flight" section and already_addressed in products/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_branch in products/signals/backend/auto_start.py; AutostartOutcome.
  • Completion and PRs: apply_report_completion and completion_state in products/signals/backend/pull_requests.py; SignalReportPullRequest in models.py; fetch_implementation_prs_for_reports in products/signals/backend/implementation_pr.py; _apply_pr_report_state in products/signals/backend/report_assignments.py.
  • Check failure re-surface: products/signals/backend/report_check_execution.py around the SignalSourceProduct.SIGNALS_CHECK emit; "Report checks" in products/signals/ARCHITECTURE.md.
  • Run-to-PR binding: find_signal_implementation_run in products/tasks/backend/facade/api.py; products/tasks/backend/webhooks.py.
  • Frontend: ArtefactLogList.tsx and artefactTypes.ts in products/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:

  1. Read helpers, root resolver, research context, duplicate_of from the in-flight check, signals_report_linked.
  2. Auto-start gate, autostart_skip artefact, PR base from the dependency, signals_autostart_skipped.
  3. Completion roll-up, follow_up_of from failed checks, the linked reports rail.

Refs #102776, #102884, #90186, #90190.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions