[#369] 🤖 - Enforce localized productagent responses

[efraespada]

📌 Summary

Enforces an exact canonical outputLocale contract for product-facing agent responses and rejects invalid or mismatched responses before GitHub publication or state mutation. Recommendation responses now use typed structured results instead of output sentinels and duplicated headings.

---

🎯 Related Issues / Tickets

• Closes [#369] 🤖 - Enforce localized productagent responses #369

---

🧩 Scope of Changes

• Added:
  • Shared locale validation and structured-query policy for Think, initial help, progress, recommendations, pull-request descriptions, and Bugbot reviews.
  • Required outputLocale fields and typed recommendation response statuses.
  • Locale boundary architecture tests and response-policy coverage.
• Updated:
  • Prompts, workflows, schemas, error handling, documentation, and generated bundles.
  • Recommendation handling to use semantic unchanged responses.
  • Validation and publication flows to retain existing state when locale validation fails.
• Removed:
  • Agent reliance on the NO_NEW_RECOMMENDATIONS output sentinel.
  • Duplicated recommendation headings.
• Refactored:
  • Product-facing agent calls to use a shared schema/options builder and canonical locale validation.

---

🛠️ Technical Details

• Every product-facing agent schema requires outputLocale, and every prompt requires the agent to echo the exact canonical targetLocale.
• Validation rejects missing, malformed, non-canonical, or mismatched locale metadata before generated content reaches publication or durable state.
• Invalid output produces the retryable locale.output-invalid application error while retaining unchanged state.
• Recommendation responses use status: recommendation | unchanged with nullable steps, allowing workflows to produce semantic results without parsing agent-output sentinels or adding duplicate headings.
• Architecture tests inventory all product-facing agent query boundaries and verify that each relevant prompt includes both targetLocale and outputLocale.

---

🔍 How to Test

1. Run pnpm test and confirm the locale policy, response schemas, workflow behavior, prompt contracts, Bugbot lifecycle, and architecture boundary tests pass.
2. Run pnpm typecheck and pnpm lint.
3. Run documentation, workflow, agent-documentation, docs-page, specification, coverage-budget, generated bundle, and architecture validation, including graphify update ..
4. Exercise a product-facing flow with the configured repository locale and confirm valid output is published.
5. Return missing, non-canonical, or mismatched outputLocale metadata from an agent and confirm the operation fails before publication or state mutation.
6. Return a recommendation with status: unchanged and steps: null and confirm no duplicate recommendation comment is created.

---

🧪 Test Coverage

• Unit tests
• Integration tests
• End-to-end (E2E) tests

---

⚠️ Breaking Changes

• None

---

🚀 Deployment Notes

• No special deployment steps

Details:

No database migration, environment variable change, or feature flag is required. Generated bundles are included and must remain synchronized with the source changes.

---

🔒 Security Considerations

• No security impact
• Input validation changes
• Authentication / authorization changes
• Sensitive data handling changes

Agent-generated product content is treated as untrusted until its structured response and exact canonical locale are validated. Invalid output is rejected before GitHub comments, reviews, descriptions, labels, or recommendation state can change.

---

📈 Performance Impact

• No performance impact

The change adds bounded schema and locale checks to existing agent workflows without changing the overall workflow model or introducing additional publication operations.

---

📝 Notes for Reviewers

Please verify that every product-facing agent task remains represented in PRODUCT_FACING_AGENT_TASKS, has a required outputLocale schema property, and validates output before its publication boundary. Pay particular attention to locale inheritance for issue and pull-request surfaces and to the semantic unchanged recommendation path.

---

✅ Checklist

• I have self-reviewed my code
• Code follows project standards and conventions
• Tests have been added or updated
• Documentation has been updated (if applicable)
• No new warnings or lint errors
• Breaking contract changes and required consumer updates are documented

---

📚 Additional Context

The change updates source code, prompts, workflows, schemas, documentation, specifications, tests, and generated bundles so the locale contract remains consistent across all product-facing agent boundaries.

[docs-page]

To preview the documentation for this pull request, visit the following URL:

docs.page/vypdev/copilot~369

Documentation is deployed and generated using docs.page

[docs-page]

To preview the documentation for this pull request, visit the following URL:

docs.page/vypdev/copilot~369

Documentation is deployed and generated using docs.page

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.11%. Comparing base (274db40) to head (b47ff20).
⚠️ Report is 702 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #369      +/-   ##
===========================================
+ Coverage    90.94%   92.11%   +1.17%     
===========================================
  Files          135      640     +505     
  Lines         6251    16442   +10191     
  Branches      1338     4244    +2906     
===========================================
+ Hits          5685    15146    +9461     
- Misses         172      523     +351     
- Partials       394      773     +379     

Files with missing lines	Coverage Δ
...application/policies/agent_output_locale_policy.ts	100.00% <100.00%> (ø)
src/application/policies/agent_response_schemas.ts	100.00% <100.00%> (ø)
...ion/usecases/actions/progress_analysis_workflow.ts	97.67% <100.00%> (ø)
.../application/usecases/actions/progress_response.ts	92.30% <100.00%> (ø)
.../usecases/actions/recommend_steps_result_policy.ts	100.00% <100.00%> (ø)
...ation/usecases/actions/recommend_steps_workflow.ts	97.50% <100.00%> (ø)
...lication/usecases/pull_request_workflow_context.ts	100.00% <100.00%> (ø)
...pplication/usecases/push_single_action_contexts.ts	98.85% <100.00%> (ø)
.../commit/bugbot/analyze_bugbot_revision_use_case.ts	92.59% <ø> (ø)
...secases/steps/commit/bugbot/build_bugbot_prompt.ts	91.83% <ø> (ø)
... and 13 more

... and 679 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[vypbot]

Current status: Overall coverage is partial; this snapshot does not prove that all of its findings are resolved.
Last reconciled on b47ff20. See aggregate Bugbot status.

🤖 Bugbot review snapshot

Bugbot reported 1 potential problem(s) when commit 8fd0046 was analyzed. This snapshot is historical; use the status block above for current state. 1 finding(s) are linked to changed code.

Findings

• medium: Unchanged status is persisted when no previous recommendation exists — src/application/usecases/actions/recommend_steps_result_policy.ts:63

[vypbot]

Bugbot: review incomplete

Current status: The review of b47ff20 has partial coverage and cannot declare the whole pull request clean.

Action: Inspect the omitted items or reduce the PR scope. Rerun the review only after changing the scope, limits, or access.

Incomplete coverage

• selection: complete; retained=1
• issue-comments: complete; retained=4
• pull-request-comments: complete; retained=1
• review-threads: complete; retained=1
• diff: partial; retained=32, omitted=19
• previous-findings: complete; retained=1
• human-conversation: partial; retained=3, truncated=1
• rules: complete; retained=0

Pull request · Verified commit · Workflow run