feat(#196): clarify architect finalization handoff (#197)

Add explicit readiness-check guidance for architect/design flows so
 unresolved questions are surfaced before finalization. Support
 design-package-only handoff, clarify how to use design notes versus
 GitHub issue drafts, and update the related repository guidance.

Author: stiwicourage

.github/agents/architect.agent.md

@@ -19,6 +19,11 @@ release automation.
 - Keep the change aligned with the repo's layering and ArchitectureGuardrails expectations.
 - Recommend the smallest structure that solves the problem cleanly.
 - Treat scope cuts, deferrals, and out-of-scope boundaries as proposals that require explicit user confirmation.
+- Before offering finalization when unresolved questions remain, summarize what is settled, what is still unresolved, and
+  present the explicit next-step choices.
+- Support two finalization modes when the discussion is sufficiently scoped:
+    - design package plus GitHub issue draft
+    - design package only
 - Once the discussion is sufficiently scoped, produce an issue-ready change design with acceptance criteria,
   out-of-scope boundaries, and a GitHub issue draft.
 
@@ -51,14 +56,18 @@ release automation.
 - Do not edit repository files unless the user explicitly asks to move from design into implementation.
 - Do not finalize the full design package until the user says the discussion is done, or you explicitly ask whether you
   should finalize it now.
+- Do not ask to finalize as if the change is fully issue-ready when unresolved questions still exist; surface those
+  unresolved items explicitly before asking how the user wants to proceed.
 - Do not finalize out-of-scope decisions unless the user has explicitly confirmed them.
 
 ## Definition of done
 
 - The affected layers and files are clearly identified.
 - The scoped implementation approach matches existing repo structure.
 - Validation, documentation impact, and follow-on agent ownership are called out explicitly.
-- A GitHub issue draft is ready to paste or create from the final output once the discussion phase is complete.
+- If the user chooses full finalization, a GitHub issue draft is ready to paste or create from the final output.
+- If the user chooses design-package-only finalization, the output is clearly resumable later from an `Open questions /
+  resume here` section.
 
 ## Must not do
 
@@ -68,5 +77,6 @@ release automation.
 - Must not create or edit repository files when the task is still in design mode.
 - Must not return a full implementation plan or finished issue draft in the first reply when the user is clearly asking
   for a design discussion.
+- Must not leave the user guessing whether the final output is a handoff document, paste-ready issue text, or both.
 - Must not decide on its own that requested work is out of scope and then finalize the design without the user's
   confirmation.

.github/copilot-instructions.md

@@ -24,8 +24,9 @@ to use one of the repository's reusable task prompts.
 For new or not-yet-scoped work, start with `.github/agents/architect.agent.md` and
 `.github/prompts/design-change.prompt.md`. That flow should stay conversational first: analyze the request, ask
 clarifying questions, present design options when needed, and only draft the final scoped solution or GitHub issue after
-the discussion is complete. Proposed scope cuts or out-of-scope boundaries must be confirmed by the user before they are
-treated as final.
+the discussion is complete. When unresolved questions still remain, architect should surface what is settled vs
+unresolved before asking whether to finalize, and should allow either full finalization or a resumable design-package-only
+handoff. Proposed scope cuts or out-of-scope boundaries must be confirmed by the user before they are treated as final.
 
 ## Repository map
 

.github/prompts/design-change.prompt.md

@@ -30,12 +30,20 @@ deferred, split into follow-up work, or excluded from the first implementation p
    exists.
 6. When you believe part of the request should be out of scope, present that as a proposal and ask the user to confirm
    or reject it. Do not silently narrow the task.
-7. Keep the conversation interactive until the user explicitly confirms the scope is correct and says the task is clear
-   enough to finalize, or until you explicitly ask whether you should now draft the final design and GitHub issue and
-   the user agrees.
-8. Only after that discussion is complete, produce the final scoped solution, implementation handoff, and GitHub issue
-   draft.
-9. Do not edit repository files unless the user explicitly switches from design to implementation.
+7. If unresolved questions still remain but the discussion is far enough along to consider finalization, pause for a short
+   readiness check before asking to finalize:
+   - list what is already settled
+   - list what is still unresolved
+   - offer three explicit choices:
+     - finalize with design package and GitHub issue draft
+     - finalize with design package only
+     - keep discussing
+8. Keep the conversation interactive until the user explicitly confirms the scope is correct and says the task is clear
+   enough to finalize, or until you explicitly ask whether you should now draft the final output and the user chooses one
+   of those options.
+9. Only after that discussion is complete, produce the final scoped solution and implementation handoff, and include the
+   GitHub issue draft only when the user chose the full-finalization option.
+10. Do not edit repository files unless the user explicitly switches from design to implementation.
 
 ## Discussion-phase output
 
@@ -47,14 +55,18 @@ Use the first response and follow-up design turns to drive a conversation, not t
 - clear trade-offs
 - a recommendation when one option is strongest
 - proposed scope and out-of-scope boundaries clearly marked as proposals until the user confirms them
+- when unresolved items remain, a readiness summary before any finalization question so the user knows what is still open
 
 Do not produce the full final design package in the first response unless the user explicitly asks for it.
 Do not convert your own proposed scope boundaries into final decisions without the user's confirmation.
 
 ## Finalization output
 
-Once the user confirms the scope and says the discussion is done, or explicitly asks for the final design, return:
+If the user chooses **design package and GitHub issue draft**, return:
 
+- a short usage note that explains:
+  - the sections before `GitHub issue draft` are design/handoff notes
+  - only the `GitHub issue draft` section is paste-ready GitHub text
 - Problem
 - Why it matters
 - Scope
@@ -66,6 +78,27 @@ Once the user confirms the scope and says the discussion is done, or explicitly
 - Recommended follow-on agent
 - GitHub issue draft
 
+If unresolved questions still remain, keep them under `Open questions` in the design package and add a short `Open
+questions` section inside the GitHub issue draft too.
+
+If the user chooses **design package only**, return:
+
+- Problem
+- Why it matters
+- Scope
+- Out of scope
+- Affected areas and likely files
+- Validation and documentation impact
+- Proposed implementation approach
+- Open questions / resume here
+- Recommended follow-on agent
+
+In design-package-only mode:
+
+- do not include a GitHub issue draft
+- preserve the settled decisions clearly enough that the user can resume later
+- end with the next unresolved design decision or a short resume prompt the user can reuse later
+
 ## Repository-specific reminders
 
 - Preserve the distinction between public PowerShell cmdlets and `% nova` CLI behavior.
@@ -75,6 +108,9 @@ Once the user confirms the scope and says the discussion is done, or explicitly
 - Draft issue text in English unless the user explicitly asks for another language.
 - If the task still has unresolved choices, end the turn with the next best question or the next design decision the
   user should make.
+- If unresolved choices remain and you offer finalization anyway, explain what is settled, what is unresolved, and what
+  each finalization option will produce.
+- If you return both design notes and a GitHub issue draft, explicitly tell the user how to use each part.
 - If you think some requested work should be deferred or excluded, ask for confirmation before turning that judgment
   into
   the final scope or issue draft.

CHANGELOG.md

@@ -12,6 +12,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- The architect/design flow now surfaces settled vs unresolved design items before finalization, offers explicit choices
+  for full finalization vs design-package-only handoff, and clarifies how to use design notes versus the paste-ready
+  GitHub issue draft.
+
 ### Deprecated
 
 ### Removed
@@ -437,4 +441,3 @@ Keep stable `Update-NovaModuleVersion` / `% nova bump` releases on the SemVer ma
 [0.0.6]: https://github.com/stiwicourage/NovaModuleTools/compare/Version_0.0.5...Version_0.0.6
 [0.0.5]: https://github.com/stiwicourage/NovaModuleTools/compare/Version_0.0.4...Version_0.0.5
 [0.0.4]: https://github.com/stiwicourage/NovaModuleTools/compare/Version_0.0.3...Version_0.0.4
-

CONTRIBUTING.md

@@ -49,7 +49,9 @@ when your Copilot session starts from the NovaModuleTools repository root.
 When you are shaping a new change, start with `architect.agent.md` and `design-change.prompt.md` so the first phase is a
 design conversation: analysis, clarifying questions, and solution options before any final scoped proposal or GitHub
 issue draft is produced. Proposed out-of-scope boundaries should be confirmed by the user before they become part of the
-final scope. Use `implement-issue.prompt.md` after the change is already scoped.
+final scope. When unresolved design questions still remain, architect should summarize what is settled vs unresolved
+before asking whether to finalize, and it should support either a full issue-ready handoff or a resumable
+design-package-only handoff. Use `implement-issue.prompt.md` after the change is already scoped.
 
 Pull requests against `main` and `develop` also run a CodeScene coverage-gate check when CI has produced the Cobertura coverage artifact, so PRs can be blocked when changed code falls below the configured coverage threshold.
 

README.md

@@ -71,7 +71,8 @@ For new or still-fuzzy work, start with `architect.agent.md` together with `desi
 lead with discussion, questions, and design options rather than a finished solution in the first reply. Use
 `implement-issue.prompt.md` once the scope, acceptance criteria, and follow-on implementation path are already clear.
 If architect proposes that part of the request is out of scope, treat that as a proposal to confirm rather than a final
-decision.
+decision. If unresolved design questions still remain, architect should first summarize what is settled vs unresolved and
+then let the user choose between full finalization, a design-package-only handoff, or continued discussion.
 
 ### Prerequisites