Skip to content

feat(agentcore): let a unit lane's reviewer record other units' findings apart - #765

Open
thenom wants to merge 1 commit into
aws-samples:mainfrom
thenom:feat/review-cross-unit-findings-760
Open

thenom wants to merge 1 commit into
aws-samples:mainfrom
thenom:feat/review-cross-unit-findings-760

Conversation

@thenom

@thenom thenom commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Closes #760

Problem

In a unit lane the author is told not to modify other units, but the stage reviewer judges the lane on every finding. A finding whose required action belongs to an already-merged unit or a shared contract counts towards NOT-READY, so the lane is sent round repair turns it can't satisfy, and a stage without a gate fails with reviewer_not_ready.

Solution

A new opt-in Terraform variable, review_cross_unit_findings ("blocking" by default, which leaves behaviour unchanged, or "advisory"), passed to the AgentCore runtime as REVIEW_CROSS_UNIT_FINDINGS. Only for a reviewer in a unit lane:

  • Brief: a "Findings for other units" block names the unit and its dependencies, and asks the reviewer to put in findings only what the author can fix within this unit, to put changes owned by another unit or a shared contract in crossUnitFindings naming the owner, and to decide READY or NOT-READY on findings alone.
  • Tool: submit_review gets an optional crossUnitFindings field, offered only in that scope. The trusted scope flag V2_REVIEW_CROSS_UNIT=1 reaches the MCP server the same way as V2_REVIEWER_AGENT.
  • Bridge: stores detail.crossUnitFindings on the reviewer sensor run and emits v2.review.cross_unit on the timeline. The repair turn and the revision findings use detail.findings only, so cross-unit items never reach the author.
  • AgentCore Gateway path (enable_mcp_gateway): the flag is carried as describe_changes is: the session and context fields, the proxy's registration, the tools Lambda's schema check, and the target's catalogue (gateway-tools.json, regenerated).

Off, outside a lane, or for a non-reviewer role, the prompt and tool schema are byte-identical to before (tested). No orchestrator change, so it is safe for running executions. Docs: verification axes in docs/concepts/workflows-and-blocks.md.

Known limits: it relies on the reviewer putting findings in the right field; the platform doesn't re-classify them, so a finding wrongly marked cross-unit skips repair. That's why it's opt-in. On a gated stage the cross-unit findings show on the timeline but aren't added to the gate's findings list.

User experience

No UI change. With the setting on, the timeline shows "Reviewer … recorded findings for other units" with the findings, and lanes stop being sent round repair turns for work they can't do.

Testing

  • review-cross-unit.test.js (brief, schema and bridge, on and off) and two run-stage.test.js lane tests.
  • Gateway: gateway-proxy, tool-definitions, tool-gateway and gateway-context tests for the field; all four fail without the Gateway wiring.
  • Full backend vitest: 7925 passed. The only failures are the four yjs-server files, which fail to import yjs from the root locally, as on clean main.
  • npm run lint (warnings only), npm run format:check, npm run dep:check, the pre-commit hook.
  • Terraform: fmt -check, validate -no-tests with the CI backend override, and the seven test suites as in CI except lambda-packaging.
  • Deployed with the setting on (in-runtime MCP server, Gateway off) to a test environment where lanes depending on merged units kept failing review on other units' gaps; the comparison of repair rounds is still being confirmed.

@github-actions github-actions Bot added area/backend Lambda APIs, lambda/shared, v2-orchestrator area/agents AgentCore runtime: CLI drivers, MCP tools, workspace and Git operations area/infra Terraform, installer and deployment size/M < 1000 changed lines (lockfiles excluded) labels Nov 13, 2026
github-actions Bot added a commit that referenced this pull request Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Automatically computed PR review signals (deterministic)

Complexity and branch coverage help focus review on functions and their tests; these signals are advisory.

Complexity and test coverage

12 changed JS/TS files analyzed · 4 flagged functions.
Coverage unavailable; test protection cannot be compared.

File / function Complexity Δ Branch coverage Δ Uncovered branches Depending files
🟠 lambda/agentcore/stage-materializer.js:587 — buildMcpConfig 21 → 24 +3 — — — 8
🟠 lambda/agentcore/persona-dispatch.js:182 — dispatchPersona 21 → 23 +2 — — — 2
🟠 lambda/agentcore/commands/run-stage.js:1886 — runStageAttempt 902 → 903 +1 — — — 1
🟠 lambda/shared/mcp/startup-context.js:60 — contextFromEnv 20 → 21 +1 — — — 3

🟢 Improving · 🟠 Needs attention · 🔴 High risk · 🟣 Highest risk

— = unavailable · n/a = not applicable · * = incomplete tests


Isobar repository map

PR impact map

This fixed repository map locates changed files and their possible reach through static links.
Red marks changed files; green marks static links, not proven runtime impact or a risk grade.

Isobar by r3al1tym.

Signals
  • A: lambda/mcp-tools/tool-gateway.js — modified file · 1 static name-match target.
  • B: lambda/shared/mcp/gateway-context.js — modified file · 2 static name-match targets.
  • Total static reach: 19 unchanged production files; 61 unchanged test files.
  • Static reach unavailable for 5 changed files.
  • Revision: 0511407; updated 2026-11-18 18:04 UTC.
Legend
  • ○ modified · ◇ added · × deleted. Blue markers: tests; gray markers: documentation.
  • Solid green: import-linked name matches. Dotted green: broader file-level import fallback.

Full report artifacts

github-actions Bot added a commit that referenced this pull request Nov 13, 2026
…ngs apart

In a unit lane the author is told not to change other units, but the
reviewer judges the lane on every finding. A finding whose fix belongs to an
already-merged unit or a shared contract counts towards NOT-READY, so the
lane is sent round repair turns it can't satisfy, and a stage without a gate
fails with reviewer_not_ready.

With review_cross_unit_findings = "advisory" (default "blocking",
unchanged), a reviewer in a unit lane:

- is told to put findings owned by another unit or a shared contract in a
  new optional submit_review field, crossUnitFindings, naming the owner, and
  to decide its verdict on its own unit's findings alone;
- has them stored on its sensor run as detail.crossUnitFindings and shown on
  the timeline as v2.review.cross_unit. Repair turns and revision findings
  use detail.findings only, so they never reach the author.

Off, outside a lane or for other roles, the prompt and tool schema are
unchanged. The flag is carried through the AgentCore Gateway path
(enable_mcp_gateway) as describe_changes is: session and context fields, the
proxy's registration, and the tools Lambda's schema and catalogue.
@thenom
thenom force-pushed the feat/review-cross-unit-findings-760 branch from 2f1d605 to 0511407 Compare November 18, 2026 17:56
github-actions Bot added a commit that referenced this pull request Nov 18, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/agents AgentCore runtime: CLI drivers, MCP tools, workspace and Git operations area/backend Lambda APIs, lambda/shared, v2-orchestrator area/infra Terraform, installer and deployment size/M < 1000 changed lines (lockfiles excluded)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Let a unit lane's reviewer record other units' findings apart from its verdict

1 participant