[#377] 🤖 - Publish one primary response for newly opened issues

[efraespada]

📌 Summary

Suppress redundant onboarding comments for newly opened issues by routing plans and initial help answers through the shared semantic reply publisher. Normal issues receive at most one primary response, while release and hotfix issues remain owned by their durable dashboards.

---

🎯 Related Issues / Tickets

• Closes [#377] 🤖 - Publish one primary response for newly opened issues #377

---

🧩 Scope of Changes

• Added:
  • Typed direct-answer projections for initial help responses.
  • Primary-response detection for plans and direct answers.
  • Read-only issue-comment querying for replay-safe fallback decisions.
  • Regression coverage for routing, sanitization, replay handling, and idempotent publication.
• Updated:
  • New-issue onboarding behavior and related documentation and specifications.
  • Recommendation replay so unchanged plans can be re-projected and reconciled.
  • Specification catalog, evidence paths, publication baseline, and generated bundles.
• Removed:
  • Direct initial-help GitHub comment publication.
  • Welcome-related context fields from the initial-help workflow.
• Refactored:
  • Initial help answers to publish through the shared correlated reply reconciler.
  • Issue routing so fallback welcomes are limited to eligible normal issues.

---

🛠️ Technical Details

Initial help now returns an immutable semantic projection instead of writing directly to GitHub. The shared reply publisher validates and sanitizes the answer, then reconciles it by correlation marker to prevent duplicate comments during event replay.

A welcome is emitted only for an eligible normal issue when no validated implementation plan or direct answer is available. Release and hotfix labels suppress this fallback, including conflicting-label cases, so their feature-owned dashboards remain the presentation path.

Before publishing a fallback, the workflow checks exact-target, bot-owned plan and direct-answer markers, including current and legacy welcome markers. If comment history cannot be read, it fails closed by omitting the welcome.

Unchanged stored recommendations are re-projected so the status reconciler can preserve or recreate the plan card without another agent call. The initial-help workflow no longer receives a GitHub mutation port, and the publication mutation baseline reflects the reduced mutation surface.

---

🔍 How to Test

1. Open a normal issue that produces a valid implementation plan and verify that one plan response is created without a separate welcome.
2. Open a question or help issue and verify that its validated answer is published once through the correlated reply path; replay the event and verify that no duplicate comment is created.
3. Open release and hotfix issues, including conflicting-label cases, and verify that no generic welcome or direct-answer onboarding response is emitted.
4. Verify that an unchanged stored recommendation is reconciled without a new agent call and that a removed plan card can be recreated.
5. Verify that malformed plans do not suppress the fallback, bot-owned markers are checked against the exact issue, and unavailable comment history omits the fallback.
6. Run the repository validation commands:
   • corepack pnpm@​10.12.4 run typecheck
   • corepack pnpm@​10.12.4 run lint
   • corepack pnpm@​10.12.4 run test:coverage
   • corepack pnpm@​10.12.4 run build
   • corepack pnpm@​10.12.4 run validate:agent-docs
   • corepack pnpm@​10.12.4 run validate:docs-page
   • corepack pnpm@​10.12.4 run validate:documentation
   • corepack pnpm@​10.12.4 run validate:workflows
   • corepack pnpm@​10.12.4 run validate:specifications
   • git diff --check

---

🧪 Test Coverage

• Unit tests
• Integration tests
• End-to-end (E2E) tests
• Manual testing only (explain why)

Coverage includes direct-answer projections, primary-response detection, fallback routing, malformed projections, sanitization, replay handling, unchanged-plan reconciliation, comment-query bindings, and idempotent publication.

---

📸 Screenshots / Recordings (UI changes only)

Not applicable. This changes GitHub issue conversation behavior without changing a graphical interface.

---

⚠️ Breaking Changes

• None

---

🚀 Deployment Notes

• Requires database migration
• Requires environment variable changes
• Requires feature flag toggle
• No special deployment steps

Details: No database migration, environment variable change, or feature flag is required. Regenerated bundles are included in the change.

---

🔒 Security Considerations

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

Initial help output must be a valid typed projection before publication, and the shared publisher sanitizes agent Markdown and GitHub control syntax. Fallback detection requires exact issue targets and bot-owned publication markers. The initial-help workflow no longer receives a GitHub mutation port.

---

📈 Performance Impact

• No performance impact
• Improves performance
• Potential performance regression (explain)

The change reuses the existing reconciliation path and adds one bounded issue-comment history read only when evaluating a possible fallback. It does not add polling or unbounded processing.

---

📝 Notes for Reviewers

Please verify the one-primary-response contract across normal, question/help, release, and hotfix routes, especially replayed events, conflicting labels, malformed plan projections, unavailable comment history, and unchanged recommendations.

---

✅ 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 UX contract is that a newly opened issue receives at most one primary conversational response: a plan, a direct answer, a feature-owned release or hotfix dashboard, or a fallback welcome. Documentation, architecture evidence, specifications, catalog entries, tests, and generated bundles were updated together.

[docs-page]

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

docs.page/vypdev/copilot~377

Documentation is deployed and generated using docs.page

[efraespada]

/copilot review

[vypbot]

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

🤖 Bugbot review snapshot

Bugbot reported 1 potential problem when commit 52096ee was analyzed. This snapshot is historical; use the status block above for current state. 1 finding is linked to changed code.

Findings

• medium: Issue replays can create a welcome after an existing plan — src/application/usecases/issue_workflow.ts:120

[vypbot]

Bugbot: review incomplete

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

Action: Inspect the omitted items or reduce the pull request 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=2
• review-threads: complete; retained=2
• diff: partial; retained=19, omitted=4
• previous-findings: complete; retained=0
• human-conversation: partial; retained=2, truncated=1
• rules: complete; retained=0

Pull request · Verified commit · Workflow run

[codecov-commenter]

Codecov Report

❌ Patch coverage is 98.43750% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 92.64%. Comparing base (274db40) to head (c1375fa).
⚠️ Report is 733 commits behind head on develop.

Files with missing lines	Patch %	Lines
...ion/policies/semantic_result_publication_policy.ts	96.87%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #377      +/-   ##
===========================================
+ Coverage    90.94%   92.64%   +1.70%     
===========================================
  Files          135      647     +512     
  Lines         6251    16794   +10543     
  Branches      1338     4286    +2948     
===========================================
+ Hits          5685    15559    +9874     
- Misses         172      481     +309     
- Partials       394      754     +360     

Files with missing lines	Coverage Δ
...ation/usecases/actions/recommend_steps_workflow.ts	97.72% <100.00%> (ø)
src/application/usecases/issue_use_case.ts	100.00% <100.00%> (ø)
src/application/usecases/issue_workflow.ts	100.00% <100.00%> (ø)
src/application/usecases/issue_workflow_context.ts	100.00% <ø> (ø)
...usecases/steps/issue/answer_issue_help_use_case.ts	100.00% <100.00%> (ø)
...usecases/steps/issue/answer_issue_help_workflow.ts	100.00% <100.00%> (ø)
...ure/composition/issue_use_case_composition_root.ts	98.46% <ø> (ø)
...ture/composition/shared_capability_port_binding.ts	100.00% <100.00%> (ø)
...ion/policies/semantic_result_publication_policy.ts	98.16% <96.87%> (ø)

... and 700 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 c1375fa. See aggregate Bugbot status.

🤖 Bugbot review snapshot

Bugbot reported 1 potential problem when commit 3a4b361 was analyzed. This snapshot is historical; use the status block above for current state. 1 finding is linked to changed code.

Findings

• low: Existing welcome comments do not suppress the fallback — src/application/policies/semantic_result_publication_policy.ts:93