@mriekki/project-forge 2.1.0 → 2.2.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "fd071b9516cb40093f30be41ab695139eb16bb4c",
+      "commit": "d4487e07e732db4129bd092f86f6ceab36b02c15",
       "version": "3.3.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "fd071b9516cb40093f30be41ab695139eb16bb4c",
+      "commit": "d4487e07e732db4129bd092f86f6ceab36b02c15",
       "version": "3.3.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -17,7 +17,7 @@
         {
           "source": "core/agents/reviewer.agent.md",
           "destination": ".github/agents/reviewer.agent.md",
-          "sha256": "ad00d8d0fad932687a8c7372e70993ba0f40f3f763a8b41fd9b6ee03a9a70df0"
+          "sha256": "94255c72a6c875722ebaf8b0cb328fe019856c01443b550ca6e2f6c422da983e"
         },
         {
           "source": "core/agents/coach.agent.md",
@@ -27,7 +27,7 @@
         {
           "source": "core/instructions/project-forge-workflow.instructions.md",
           "destination": ".github/instructions/project-forge-workflow.instructions.md",
-          "sha256": "1cd1677a5692d00c252a3b38a07e7ae1b70edc0bd23436b8c2c424efb62217e1"
+          "sha256": "aa03af8ef23d32d90a85adaeb549873e4de32798c58bfdaf7fe4183a549b1a17"
         },
         {
           "source": "core/instructions/project-forge-docs.instructions.md",
@@ -37,7 +37,7 @@
         {
           "source": "core/skills/define-feature/SKILL.md",
           "destination": ".github/skills/define-feature/SKILL.md",
-          "sha256": "1efa4c18d41deb4b26f132d440d881310864f8b0d37423d6b23431efeedb2e78"
+          "sha256": "c9f85d76a701b3d1af5c70cd74b19ce119b5735cf3537e2618159d58394ffd02"
         },
         {
           "source": "core/skills/grill-me/SKILL.md",
@@ -47,22 +47,22 @@
         {
           "source": "core/skills/grill-with-docs/SKILL.md",
           "destination": ".github/skills/grill-with-docs/SKILL.md",
-          "sha256": "c2c24089f5f5437de1702777dc60e794e26a1a0919eba7e39c32d137fdf23471"
+          "sha256": "facdfecee977ab01bbe908f6f122e483ea27c98a8f1562973f59f9266b63323e"
         },
         {
           "source": "core/skills/refine-requirements/SKILL.md",
           "destination": ".github/skills/refine-requirements/SKILL.md",
-          "sha256": "70ee4dcf4fd3568c835428dae4b2a830604793d3d486e1c903c26e100fab6e64"
+          "sha256": "ee5085ac6bbf8fb33ab5f6b52e0ac954c164fd3ea51f90965c9bde86adc88def"
         },
         {
           "source": "core/skills/start-work/SKILL.md",
           "destination": ".github/skills/start-work/SKILL.md",
-          "sha256": "edc58cdd20c3401ee20a725e18063e604830396f6b88f9bf2555b3f043362c7f"
+          "sha256": "5f4d46323d19bb7a1d4e64f233ae64aae8e1874da072d38cb344d3d834bdea8e"
         },
         {
           "source": "core/skills/setup/SKILL.md",
           "destination": ".github/skills/setup/SKILL.md",
-          "sha256": "e700e914afc291ffb1153bb796a8ef150c624c5b54032e29d3abda221260285f"
+          "sha256": "c295193b341accf03a35105e2e4defdf11aee0198b1e24b74ab371f3a6824985"
         },
         {
           "source": "core/skills/build/SKILL.md",
@@ -92,32 +92,32 @@
         {
           "source": "core/skills/next-step/SKILL.md",
           "destination": ".github/skills/next-step/SKILL.md",
-          "sha256": "68c05ad11f9c9fad7b0bc122995ca259fd54c523cb1fa5ac0e105ae523ef9d86"
+          "sha256": "7c24a15b9069dcc5218319ab7fb72231e48efd2ebd325d8ff250e142cb3aa813"
         },
         {
           "source": "core/skills/deliver/SKILL.md",
           "destination": ".github/skills/deliver/SKILL.md",
-          "sha256": "ffe9dbc862f83828b3acd8f8bf49ea912b7998dc0c844655bf83dfafcf7f4434"
+          "sha256": "238d6c81a7253c4241e4cf8588be5a5986b406b7e3a56cac115fc47a46071c71"
         },
         {
           "source": "core/skills/cleanup-branches/SKILL.md",
           "destination": ".github/skills/cleanup-branches/SKILL.md",
-          "sha256": "99b082f5a6eb183161bc6dc2f40e383e744a4443e6e3c56615ca9d010845eaf8"
+          "sha256": "b44af82b8e21693fcc600cb9628c50f49a117c7cfb7840af0f2ccedad2f96dc7"
         },
         {
           "source": "core/skills/pull-latest/SKILL.md",
           "destination": ".github/skills/pull-latest/SKILL.md",
-          "sha256": "ca7dc6669c6eb81fd3a7961dc123cc9822fcccb7da3e86e3391f5f92b15fe093"
+          "sha256": "709471b55c41ec72fe0ca4eb87af0740ab9a947ef0b31c36f8cf51afc58d3ccb"
         },
         {
           "source": "core/skills/project-forge-update/SKILL.md",
           "destination": ".github/skills/project-forge-update/SKILL.md",
-          "sha256": "70170e57a77f143c719a8c349161c580e339397e782d28133d9f3734f6625847"
+          "sha256": "3463a68171fa30ef10f1ca514424236317ec364f015c5446f49911a1a3c9bb12"
         },
         {
           "source": "core/skills/core-sync/SKILL.md",
           "destination": ".github/skills/core-sync/SKILL.md",
-          "sha256": "97accdf58527f51c0e5f5b8e6a75468d9d687bc2c07dcd9ab6ff1bef9f103c58"
+          "sha256": "cbc498597cea7a48004fc507f9a6efc130544e57f347c0efdbb073f71f14965e"
         },
         {
           "source": "core/skills/upstream-fix/SKILL.md",
@@ -142,7 +142,7 @@
         {
           "source": "core/skills/deploy/SKILL.md",
           "destination": ".github/skills/deploy/SKILL.md",
-          "sha256": "7bacd366014bf8c890328ec2b78412a39a0abff2f6b44dd53ca129102a7a30c8"
+          "sha256": "a2092940eea537223abcd4ed1cbea20dccdead538b21841b305f243686715af0"
         },
         {
           "source": "core/skills/tear-down/SKILL.md",
@@ -172,7 +172,7 @@
         {
           "source": "core/skills/code-walkthrough/SKILL.md",
           "destination": ".github/skills/code-walkthrough/SKILL.md",
-          "sha256": "0391f98dac6dfd41882c330425567ae595fde01fce63de521563c95647d2b889"
+          "sha256": "34cb60680a3effc6af3a5ec22fe0c20d4b9b8064b8b808afed673be988b0f210"
         },
         {
           "source": "core/skills/learning-review/SKILL.md",
@@ -202,12 +202,12 @@
         {
           "source": "core/process/GUIDED_NEXT_STEPS.md",
           "destination": "docs/process/GUIDED_NEXT_STEPS.md",
-          "sha256": "3a6ec8523fdb1c4f4e357b13fc712bd7f732ea9cd25754ae4f8c84fb438f2452"
+          "sha256": "f25f08e6b2e904f44652fb7ea78b9f576f544a55950d63741b6f4806e4ee3287"
         },
         {
           "source": "core/process/INTERACTIVE_SESSION_GUIDE.md",
           "destination": "docs/process/INTERACTIVE_SESSION_GUIDE.md",
-          "sha256": "15d47509919e83786ada6df1e5482bd9f73ca4955cda66287f6d6b1f9722c853"
+          "sha256": "c35f2f4bc1b52746b205eab65982b32d9a2fe58f1c750f9744ddfdd320c3f52c"
         },
         {
           "source": "core/process/COACHING_GUIDE.md",

package/assets/generated/core/core/agents/reviewer.agent.md

@@ -72,7 +72,7 @@ READY / CHANGES REQUIRED / INSUFFICIENT EVIDENCE
 
 ## Guided ending
 
-After findings use CURRENT STATE, RECOMMENDED NEXT STEP, and a small OPTIONS menu. Reviewer itself does not commit, push, create/merge PRs, or deploy.
+After findings use CURRENT STATE, RECOMMENDED NEXT STEP, and a small set of relevant action choices. When the host exposes structured question controls, render mutually exclusive actions through **single-select** UI following `INTERACTIVE_SESSION_GUIDE.md`; in VS Code use the native question surface such as `vscode_askQuestions`. Use a numbered text menu only when structured choice UI is unavailable. Reviewer itself does not commit, push, create/merge PRs, or deploy.
 
 When implementation is READY and the human accepts the meaningful local diff, explicitly recommend:
 

package/assets/generated/core/core/instructions/project-forge-workflow.instructions.md

@@ -20,7 +20,11 @@ For implementation, establish the repository-appropriate short-lived work branch
 
 Continuous modes such as `/grill-me`, `/grill-with-docs`, `/refine-requirements`, `/coach`, `/learning-review`, and `/deployment-readiness` continue until stopped or naturally complete.
 
-During interactive questioning, prefer concise choice-first options for genuinely bounded human decisions, including `Other / specify` and `Not sure — recommend one` when appropriate. Keep factual/environment-specific values and questions intended to elicit the human's own framing, reasoning, debugging approach, design rationale, or understanding open-ended unless options are later useful as scaffolding.
+During interactive questioning, prefer concise choice-first options for genuinely bounded human decisions, including `Other / specify` and `Not sure — recommend one` when appropriate. When the host exposes native structured question controls, use them instead of a plain numbered chat list. In VS Code, use the host's structured question surface such as `vscode_askQuestions` when available: single-select for mutually exclusive decisions/actions and multi-select only when several simultaneous selections are valid. A textual numbered menu is only the fallback when structured choice UI is unavailable.
+
+Make a recommendation only when current evidence, repository policy, or a clear engineering tradeoff supports one. Mark exactly one supported choice with the host's `recommended` indicator when available and give a brief rationale. If no option is clearly better, do not mark any option recommended. A recommendation is advice, not approval: record only the human's selected/confirmed answer. If the human asks for no recommendation on one decision, honor that for that decision only; later questions may still include evidence-backed recommendations.
+
+Keep factual/environment-specific values and questions intended to elicit the human's own framing, reasoning, debugging approach, design rationale, or understanding open-ended unless options are later useful as scaffolding.
 
 For deployment readiness, inspect existing non-secret configuration before asking setup questions. Show already-known simple machine facts such as hostname/address, deployment user, port, and target OS for confirmation. Ask only for missing or conflicting facts. Keep deployment-tool implementation identifiers such as logical target names, `targetName`, SSH aliases, profile paths, and trust-file paths internal unless troubleshooting or genuine ambiguity requires them.
 

package/assets/generated/core/core/process/GUIDED_NEXT_STEPS.md

@@ -11,18 +11,34 @@ CURRENT STATE
 RECOMMENDED NEXT STEP
 <one action and why>
 
-OPTIONS
+CHOICES
+<only the relevant bounded actions, rendered through host structured choice UI when available>
+
+RECOMMENDED PATH
+<only when multiple future steps are useful>
+```
+
+For the current choice, follow `INTERACTIVE_SESSION_GUIDE.md`:
+
+- use the host's structured choice UI when available; in VS Code use the native question surface such as `vscode_askQuestions`;
+- action menus are normally **single-select** because the developer is choosing one next action;
+- use multi-select only when the workflow explicitly permits several simultaneous selections;
+- make the recommended choice visible when evidence supports one;
+- include `Other / specify` or free-text when the action space may be incomplete;
+- keep genuinely open-ended questions open-ended.
+
+A textual numbered menu is only the documented fallback when no structured choice UI is available. Fallback shape:
+
+```text
+OPTIONS — TEXT FALLBACK ONLY
 1. ... [READ ONLY]
 2. ... [MODIFIES DOCS]
 3. ... [MODIFIES FILES]
 4. ... [GIT + GITHUB WRITE]
 5. Stop [NO ACTION]
-
-RECOMMENDED PATH
-<only when multiple future steps are useful>
 ```
 
-Show only relevant options.
+Show only relevant choices.
 
 Standard action labels include:
 
@@ -41,7 +57,7 @@ Standard action labels include:
 [NO ACTION]
 ```
 
-A selected option authorizes only the bounded action described, except where a skill explicitly defines a continuous session or compound mechanical action.
+A selected choice authorizes only the bounded action described, except where a skill explicitly defines a continuous session or compound mechanical action.
 
 A manually invoked compound action skill may itself be the bounded authorization for its routine mechanics. `/deliver`, for example, may proceed through safe short-lived-branch setup/recovery, staging, commit, push, PR creation/update, and CI inspection without inserting separate options for each mechanical step. It still stops at its explicit merge/finalize gate and whenever evidence becomes ambiguous or unsafe.
 

package/assets/generated/core/core/process/INTERACTIVE_SESSION_GUIDE.md

@@ -27,12 +27,42 @@ Choose the question shape based on what the interaction is trying to learn or de
 When a material question has a reasonable bounded answer space and the human is choosing or confirming a decision, prefer a concise choice-first presentation:
 
 - offer a small set of plausible choices, normally 3-6;
-- mark a materially preferred option as `RECOMMENDED` when current evidence or repository guidance justifies it;
 - include `Other / specify` when the choices are not exhaustive;
 - include `Not sure — recommend one` when the human can reasonably delegate the choice;
 - accept a choice label/text or a free-form answer;
 - treat choices as interaction aids, not additional requirements.
 
+### Host-native structured choice UI
+
+When the current host exposes a structured question/choice UI, use it for bounded choices instead of rendering a plain numbered chat menu. In VS Code, use the native question surface exposed by the host, such as `vscode_askQuestions` when available.
+
+Presentation rules:
+
+- use **single-select** when the choices are mutually exclusive or one action is being authorized;
+- use **multi-select** only when selecting several choices at the same time is semantically valid;
+- preserve one-material-question-at-a-time cadence whenever practical even if the host can batch questions;
+- keep consequence/action labels such as `[READ ONLY]`, `[REQUIREMENTS GATE]`, or `[GIT + GITHUB WRITE]` visible when they matter to authorization;
+- include `Other / specify` or host-supported free-text input when the option set may be incomplete; after `Other / specify`, collect the missing value without forcing another invented menu;
+- accept equivalent free-text answers even when a structured selector is shown, unless the host UI itself requires a selection;
+- map the returned structured value to the same semantic choice the workflow would have accepted by label/text.
+
+### Recommendations inside choices
+
+A recommendation is optional advice, not a required field and not an accepted decision.
+
+- mark **exactly one** choice as `RECOMMENDED` only when current evidence, repository policy, or a clear engineering tradeoff supports it;
+- use the host's `recommended` indicator/metadata when available and add a brief rationale in the choice description or surrounding prompt;
+- do not mark multiple choices recommended;
+- do not invent a preference merely to populate recommendation metadata;
+- when no option is clearly better, present the choices with **no recommendation**;
+- if the human asks for no recommendation on a specific decision, omit the recommendation for that question only; later questions may still include evidence-backed recommendations;
+- the human may select a different option or answer free-form;
+- record only the human's selected/confirmed answer as the requirement, action, or decision. Never record the recommendation itself as accepted state.
+
+A structured selector is presentation, not extra authorization. Selecting a choice authorizes only the action/session that the workflow says that choice authorizes.
+
+When the host has no structured question UI, use a concise textual fallback. A numbered list is acceptable **only as this fallback**; keep the same labels/recommendation/consequence tags and accept the number, label, or a free-form answer. Do not use a plain numbered list as the normal VS Code interaction when native structured choice UI is available.
+
 Keep questions open-ended when predefined choices would weaken the purpose of the interaction. This includes:
 
 - user-authored problem/outcome/workflow framing where the human's own wording matters;

package/assets/generated/core/core/skills/cleanup-branches/SKILL.md

@@ -114,18 +114,14 @@ If no branch is safely deletable, stop after the preview.
 
 ## 5. Cleanup gate
 
-For a non-empty verified-safe set, present one bounded destructive gate:
+For a non-empty verified-safe set, present one bounded destructive gate using the host-native **single-select structured choice UI** when available; in VS Code use the native question surface such as `vscode_askQuestions`. Offer:
 
-```text
-BRANCH CLEANUP READY
-
-1. Delete verified-safe local + remote branches [GIT + GITHUB WRITE] — recommended
-2. Delete verified-safe remote branches only [GITHUB WRITE]
-3. Delete verified-safe local branches only [GIT WRITE]
-4. Stop [NO ACTION]
-```
+- `Delete verified-safe local + remote branches` `[GIT + GITHUB WRITE]` — `RECOMMENDED`
+- `Delete verified-safe remote branches only` `[GITHUB WRITE]`
+- `Delete verified-safe local branches only` `[GIT WRITE]`
+- `Stop` `[NO ACTION]`
 
-Only the selected option authorizes the corresponding deletions. Do not include REVIEW REQUIRED branches in the bounded action.
+Use a numbered text menu only when structured choice UI is unavailable. Only the selected choice authorizes the corresponding deletions. Do not include REVIEW REQUIRED branches in the bounded action.
 
 ## 6. Revalidate before deletion
 

package/assets/generated/core/core/skills/code-walkthrough/SKILL.md

@@ -58,6 +58,8 @@ Deep    — important methods/blocks, state/data flow, dependencies, edge cases,
 
 Depth may vary by file. Treat trivial configuration lightly unless it materially affects behavior; spend more depth on implementation anchors.
 
+If the human needs to choose a depth, use host-native **single-select structured choice UI** when available. Do not recommend a depth unless the requested learning goal or change complexity clearly supports one; `Focused` is a descriptive default, not permission to manufacture a recommendation.
+
 ## 4. Build the walkthrough plan
 
 Before explaining the first file:
@@ -125,13 +127,15 @@ Group trivial generated/configuration changes when that improves learning, but d
 
 Default to one file or one tightly related file group at a time. Do not dump the whole implementation at once.
 
-At a natural file boundary, show a compact navigation cue such as:
+At a natural file boundary, a compact navigation cue may be shown:
 
 ```text
 NEXT: <suggested file>
 Use: next | deeper | explain this | trace | why this design | diagram | quiz | debug | interview | skip | stop
 ```
 
+When the host exposes structured choice UI and the human is being asked to choose among these navigation actions, prefer a relevant **single-select** subset rather than forcing the human to type a token. Keep free-text commands valid. Do not turn the full command vocabulary into a large mandatory selector when the next action is already obvious.
+
 Interpret these naturally:
 - `next` — continue to the suggested next file;
 - `deeper` — increase depth for the current file/topic;
@@ -185,13 +189,13 @@ When the planned change set is covered or the human stops, summarize:
 - learning gaps or topics worth revisiting,
 - optional next learning actions.
 
-Offer only relevant next choices, such as:
+When offering bounded next actions, use host-native **single-select structured choice UI** when available. Relevant choices may include:
 
-```text
-1. /learning-review <same scope> [READ ONLY]
-2. /coach <specific concept> [READ ONLY]
-3. Return to engineering workflow [NO ACTION]
-4. Stop [NO ACTION]
-```
+- `/learning-review <same scope>` `[READ ONLY]`
+- `/coach <specific concept>` `[READ ONLY]`
+- `Return to engineering workflow` `[NO ACTION]`
+- `Stop` `[NO ACTION]`
+
+Recommend at most one only when the walkthrough evidence shows a clear learning gap or the engineering workflow is clearly the better next step; otherwise present the choices without a recommendation. Use a numbered text menu only when structured choice UI is unavailable.
 
 Do not create a new engineering state such as `CODE_WALKTHROUGH_PENDING`. Walkthrough completion is learning evidence, not a delivery gate.

package/assets/generated/core/core/skills/core-sync/SKILL.md

@@ -94,7 +94,9 @@ If the checkout is dirty, ahead, diverged, intentionally pinned, or ambiguous, p
 
 ## 5. Present one bounded component-sync choice
 
-For a safe local source:
+Use the host-native **single-select structured choice UI** when available because exactly one next action is authorized. In VS Code use the native question surface such as `vscode_askQuestions`. Preserve the consequence labels and show the recommended choice. Use a numbered text list only when structured choice UI is unavailable.
+
+For a safe local source, show the evidence:
 
 ```text
 CORE SYNC READY
@@ -102,13 +104,15 @@ CORE SYNC READY
 Consumer baseline: <commit/version>
 Source: LOCAL <core-path>
 Distribution: <distribution>
-
-1. Sync the component-only Core baseline [GIT + FILE WRITE] — recommended
-2. Keep inspecting only [READ ONLY]
-3. Stop [NO ACTION]
 ```
 
-For a configured remote source:
+Then offer:
+
+- `Sync the component-only Core baseline` `[GIT + FILE WRITE]` — `RECOMMENDED`
+- `Keep inspecting only` `[READ ONLY]`
+- `Stop` `[NO ACTION]`
+
+For a configured remote source, show:
 
 ```text
 CORE SYNC READY
@@ -116,17 +120,19 @@ CORE SYNC READY
 Consumer baseline: <commit/version>
 Source: REMOTE PROVIDER
 Provider: <provider repository>
-
-1. Request remote Core sync [REMOTE WRITE] — recommended
-2. Keep inspecting only [READ ONLY]
-3. Stop [NO ACTION]
 ```
 
+Then offer:
+
+- `Request remote Core sync` `[REMOTE WRITE]` — `RECOMMENDED`
+- `Keep inspecting only` `[READ ONLY]`
+- `Stop` `[NO ACTION]`
+
 The selected choice does not authorize merge, release publication, or deployment.
 
 ## 6. Local component path
 
-After local option 1 is selected:
+After `Sync the component-only Core baseline` is selected:
 
 1. Refresh Core remote state.
 2. Reclassify the accepted/default Core branch.

package/assets/generated/core/core/skills/define-feature/SKILL.md

@@ -63,7 +63,7 @@ Do not create a competing source of truth.
 
 Ask one material question at a time when a real decision is unresolved.
 
-For bounded decisions with a small credible answer space, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Keep initial product/problem framing, desired outcomes, workflows, and other answers that need the human's own wording open-ended rather than constraining them to invented options.
+For bounded decisions with a small credible answer space, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. When the host exposes structured choice controls, render mutually exclusive alternatives through single-select UI rather than a plain numbered menu; use multi-select only when several simultaneous selections are actually valid. Keep `Other / specify` or free-text available when choices may be incomplete. Keep initial product/problem framing, desired outcomes, workflows, and other answers that need the human's own wording open-ended rather than constraining them to invented options.
 
 Clarify only what matters, such as:
 - user/engineering outcome,
@@ -123,22 +123,13 @@ If systematic lower-level coverage is valuable, recommend:
 
 ## 7. Guided ending
 
-Use a small evidence-backed menu, for example:
+Use a small evidence-backed set of relevant actions. In VS Code, render them through the host-native **single-select structured choice UI** such as `vscode_askQuestions` when available. Conceptual choices may include:
 
-```text
-CURRENT STATE
-<what is defined and what remains open>
-
-RECOMMENDED NEXT STEP
-<one action and why>
-
-OPTIONS
-1. Review definition [READ ONLY]
-2. Grill unresolved behavior [READ ONLY]
-3. Refine detailed requirements [READ ONLY initially]
-4. Approve requirements/scope when applicable [REQUIREMENTS GATE]
-5. Start work if already ready [READ ONLY]
-6. Stop [NO ACTION]
-```
+- `Review definition` `[READ ONLY]`
+- `Grill unresolved behavior` `[READ ONLY]`
+- `Refine detailed requirements` `[READ ONLY initially]`
+- `Approve requirements/scope` `[REQUIREMENTS GATE]` when applicable
+- `Start work` `[READ ONLY]` when already ready
+- `Stop` `[NO ACTION]`
 
-Only show relevant options. A file-changing choice authorizes only that bounded action/session.
+Make the recommended next action visible when evidence supports one. Use a numbered text menu only when structured choice UI is unavailable. A file-changing choice authorizes only that bounded action/session.

package/assets/generated/core/core/skills/deliver/SKILL.md

@@ -197,7 +197,7 @@ If a Draft PR was required earlier and all readiness conditions are now satisfie
 
 ## 8. Single merge + finalize gate
 
-When PR evidence still matches the accepted implementation and CI/policy are satisfactory, combine final PR acceptance and merge authorization into one meaningful gate:
+When PR evidence still matches the accepted implementation and CI/policy are satisfactory, combine final PR acceptance and merge authorization into one meaningful gate. First show:
 
 ```text
 MERGE READY
@@ -206,13 +206,17 @@ PR CI: GREEN
 Reviewer: READY
 PR diff: matches accepted delivery scope
 Mergeable/policy: <observed state>
-
-1. Merge and finalize delivery [HUMAN ACCEPTANCE + GITHUB/GIT WRITE] — recommended
-2. Review final PR diff first [READ ONLY]
-3. Leave PR open [NO ACTION]
 ```
 
-Selecting option 1 means:
+Then render the mutually exclusive gate through the host-native **single-select structured choice UI** when available. In VS Code use the native question surface such as `vscode_askQuestions`. Offer:
+
+- `Merge and finalize delivery` `[HUMAN ACCEPTANCE + GITHUB/GIT WRITE]` — `RECOMMENDED`
+- `Review final PR diff first` `[READ ONLY]`
+- `Leave PR open` `[NO ACTION]`
+
+Use a numbered text list only when structured choice UI is unavailable.
+
+Selecting `Merge and finalize delivery` means:
 - the human accepts the final PR as observed,
 - merge is authorized using the repository-approved strategy,
 - applicable post-merge default-branch CI/policy may be observed/rechecked automatically,
@@ -247,7 +251,7 @@ Only after configured post-merge default-branch CI and any additional observable
 
 ## 10. Delivered-branch finalization
 
-For a normal short-lived delivered branch, option 1 at the merge gate already authorizes finalization. Do not ask a separate `Delete branch?` question.
+For a normal short-lived delivered branch, the `Merge and finalize delivery` gate choice already authorizes finalization. Do not ask a separate `Delete branch?` question.
 
 Preserve by default:
 - the configured default branch,
@@ -394,4 +398,4 @@ The optional learning handoff does not block or replace deployment readiness whe
 
 `/deliver` takes reviewed/accepted work through routine branch/commit/push/PR/CI mechanics automatically, then stops once for the merge-and-finalize decision. After successful engineering completion it may prepare disposable learning workbenches and shows an optional learning handoff without creating another gate.
 
-`/cleanup-branches` is the standalone preview-first path for accumulated, previously retained, unrelated, or otherwise out-of-band branch housekeeping.
+`/cleanup-branches` is the standalone preview-first path for accumulated, previously retained, unrelated, or otherwise out-of-band branch housekeeping.

package/assets/generated/core/core/skills/deploy/SKILL.md

@@ -33,7 +33,7 @@ Resolve exact configured name, purpose/Production classification, placement, iso
 
 If `demo` exists, `/deploy demo` targets exactly `demo`. If `prod-east` has purpose `production`, `/deploy prod-east` remains a Production deployment even though the literal name differs.
 
-If no environment is named, enumerate configured environments and ask the human to choose; never silently default to Production. The deployment workflow must never fall back to another environment/placement/host/provider because deployment fails.
+If no environment is named, enumerate configured environments and ask the human to choose through host-native **single-select structured choice UI** when available; in VS Code use the native question surface such as `vscode_askQuestions`; never silently default to Production. Do not recommend an environment unless current project evidence or the user's stated deployment goal clearly supports one. The deployment workflow must never fall back to another environment/placement/host/provider because deployment fails.
 
 If the requested environment is missing or ambiguous, route to `/setup` rather than guessing.
 
@@ -73,7 +73,7 @@ immutable application image/release policy
 smoke validation
 ```
 
-When a bounded choice is useful, provide a small recommended menu plus `Other / specify` and `Not sure — recommend one`.
+When a bounded choice is useful, follow `INTERACTIVE_SESSION_GUIDE.md`: use host-native structured choice UI when available, single-select for mutually exclusive values and multi-select only when several simultaneous selections are valid. Keep `Other / specify` or free-text available when the choices may be incomplete. Recommend at most one option, only when evidence or a clear engineering tradeoff supports it, and explain why briefly; otherwise show the choices without a recommendation. Record only the human's selected/confirmed answer.
 
 Once these facts are durably established, later deployments should be routine rather than repeating onboarding.
 

package/assets/generated/core/core/skills/grill-with-docs/SKILL.md

@@ -34,7 +34,7 @@ Ask one material question at a time and challenge:
 - architecture/operational tradeoffs,
 - testability.
 
-When the challenge is a bounded decision with a small credible option set, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md` and explain important tradeoffs. When the purpose is to expose or strengthen the human's reasoning, ask open-ended first; introduce options or hints later only when useful as scaffolding.
+When the challenge is a bounded decision with a small credible option set, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md` and explain important tradeoffs. Use host-native single-select UI for mutually exclusive alternatives when available, and multi-select only when several choices may be valid together. When the purpose is to expose or strengthen the human's reasoning, ask open-ended first; introduce options or hints later only when useful as scaffolding.
 
 Cadence:
 
@@ -66,15 +66,13 @@ For local-document models, common homes are:
 
 Invocation alone does not imply broad document-write permission.
 
-When document changes are needed, present a bounded choice such as:
+When document changes are needed, present a bounded **single-select structured choice** through the host UI when available. In VS Code use the native question surface such as `vscode_askQuestions`. Relevant choices are:
 
-```text
-1. Continue grilling only [READ ONLY]
-2. Reconcile resolved decisions during this session [MODIFIES DOCS]
-3. Stop [NO ACTION]
-```
+- `Continue grilling only` `[READ ONLY]`
+- `Reconcile resolved decisions during this session` `[MODIFIES DOCS]`
+- `Stop` `[NO ACTION]`
 
-After option 2 is selected, focused updates to the permitted current work-item documents are authorized for the active session. Do not ask again after each answer.
+Use a numbered text list only when structured choice UI is unavailable. After `Reconcile resolved decisions during this session` is selected, focused updates to the permitted current work-item documents are authorized for the active session. Do not ask again after each answer.
 
 Pause only when a new answer would change higher-level approved scope, contradict another authority/ADR, or require a new cross-cutting decision.
 

package/assets/generated/core/core/skills/next-step/SKILL.md

@@ -70,7 +70,7 @@ When deterministic setup passes but human workspace acceptance is still needed,
 
 When the workspace is accepted and the first approved work item is clear, recommend `/start-work <ID>`.
 
-If the developer wants the broader status instead of one action, offer `/progress` as a read-only option.
+If the developer wants the broader status instead of one action, offer `/progress` as a read-only choice.
 
 ## 3. Engineering/delivery states
 
@@ -111,14 +111,13 @@ CURRENT STATE
 RECOMMENDED NEXT STEP
 <one action and why>
 
-OPTIONS
-1. ... [READ ONLY]
-2. ... [MODIFIES FILES]
-3. ... [GIT + GITHUB WRITE]
-4. Stop [NO ACTION]
+CHOICES
+<only relevant bounded actions, rendered through structured choice UI when available>
 ```
 
-Only show relevant options. `/next-step` orients; it does not become another workflow database.
+When there is more than one relevant action, use the host's native **single-select structured choice UI** following `INTERACTIVE_SESSION_GUIDE.md`. In VS Code, use the question surface such as `vscode_askQuestions` when available. Keep consequence labels visible, mark the recommended choice where evidence supports one, and include `Other / specify` or free-text only when the action space may be incomplete. Use multi-select only for an explicitly multi-action workflow; ordinary `/next-step` choices are mutually exclusive.
+
+A textual numbered `OPTIONS` list is only the fallback when no structured choice UI is available. Only show relevant choices. `/next-step` orients; it does not become another workflow database.
 
 For an unprepared generated workspace, a good result is simply:
 
@@ -128,12 +127,10 @@ Local setup has not been completed on this computer.
 
 RECOMMENDED NEXT STEP
 /setup
-
-OPTIONS
-1. /progress [READ ONLY]
-2. Stop [NO ACTION]
 ```
 
+If useful, offer `/progress` `[READ ONLY]` and `Stop` `[NO ACTION]` through the structured selector; do not print a numbered menu in normal VS Code use.
+
 ## 5. Optional documentation and learning choices
 
 When implementation is stable enough to understand or document, `/next-step` may offer these choices without making them gates:
@@ -147,6 +144,8 @@ When implementation is stable enough to understand or document, `/next-step` may
 /system-lab [changes <work-item>]
 ```
 
+If the human is being asked to select one of these bounded next actions, use the same single-select structured-choice rule. The command list above is descriptive, not a required numbered menu.
+
 Prefer `/docs` for the coherent project briefing/document map, `/code-walkthrough` for implementation flow, `/db-lab` for concrete schema/query/index/ORM evidence, and `/system-lab` for architecture/runtime/failure/scale evidence.
 
 Safe generated projections may be prepared automatically. Do not silently rewrite project-owned prose, accept an ADR, or make learning mandatory before `/deliver` unless the approved work item explicitly requires it.

package/assets/generated/core/core/skills/project-forge-update/SKILL.md

@@ -124,7 +124,7 @@ For a Bootstrap-generated consumer, also preview the companion generated-consume
 
 ## 5. Present one bounded update choice
 
-When the exact target package plan and any generated-consumer companion plan are safe, present:
+When the exact target package plan and any generated-consumer companion plan are safe, show the reviewed evidence:
 
 ```text
 PROJECT FORGE UPDATE READY
@@ -137,13 +137,17 @@ Core: <old> → <new>
 Deployment: <old> → <new> / unchanged
 Generated consumer metadata: <not present / coherent update planned>
 Managed drift/conflicts: NONE
-
-1. Apply the exact Project Forge package update [GIT + FILE WRITE] — recommended
-2. Keep inspecting only [READ ONLY]
-3. Stop [NO ACTION]
 ```
 
-Choosing option 1 authorizes only:
+Then use the host-native **single-select structured choice UI** when available; in VS Code use the native question surface such as `vscode_askQuestions`. Offer:
+
+- `Apply the exact Project Forge package update` `[GIT + FILE WRITE]` — `RECOMMENDED`
+- `Keep inspecting only` `[READ ONLY]`
+- `Stop` `[NO ACTION]`
+
+Use a numbered text menu only when structured choice UI is unavailable.
+
+Choosing `Apply the exact Project Forge package update` authorizes only:
 
 - creation/switch to one repository-appropriate short-lived update branch when needed;
 - exact target package apply;

package/assets/generated/core/core/skills/pull-latest/SKILL.md

@@ -49,21 +49,25 @@ Never use `reset --hard`, force-push, merge, or rebase as part of `/pull-latest`
 
 ## 3. Choose the update target
 
+When the user must choose an update action, use the host-native **single-select structured choice UI** when available; in VS Code use the native question surface such as `vscode_askQuestions`. Use a numbered text menu only when structured choice UI is unavailable.
+
 If the human supplied a branch, use that branch as the requested target when it can be resolved safely.
 
-If no branch was supplied and the current branch is the default branch, present:
+If no branch was supplied and the current branch is the default branch, show:
 
 ```text
 PULL LATEST READY
 
 Current branch: <branch>
 Working tree: CLEAN
-
-1. Refresh remote state and pull latest <branch> [GIT WRITE] — recommended
-2. Stop [NO ACTION]
 ```
 
-If no branch was supplied and the current branch is a non-default branch, present:
+Then offer:
+
+- `Refresh remote state and pull latest <branch>` `[GIT WRITE]` — `RECOMMENDED`
+- `Stop` `[NO ACTION]`
+
+If no branch was supplied and the current branch is a non-default branch, show:
 
 ```text
 PULL LATEST READY
@@ -71,13 +75,15 @@ PULL LATEST READY
 Current branch: <branch>
 Default branch: <default>
 Working tree: CLEAN
-
-1. Refresh and pull the current branch [GIT WRITE]
-2. Switch to the default branch and pull latest [GIT WRITE] — recommended for returning to baseline
-3. Stop [NO ACTION]
 ```
 
-Only the selected option authorizes fetch/switch/pull mechanics for the selected branch.
+Then offer:
+
+- `Refresh and pull the current branch` `[GIT WRITE]`
+- `Switch to the default branch and pull latest` `[GIT WRITE]` — `RECOMMENDED` when returning to baseline
+- `Stop` `[NO ACTION]`
+
+Only the selected choice authorizes fetch/switch/pull mechanics for the selected branch.
 
 ## 4. Refresh remote state
 

package/assets/generated/core/core/skills/refine-requirements/SKILL.md

@@ -113,22 +113,24 @@ STATUS
 <DRAFT / APPROVED / external status / not represented locally>
 ```
 
-Then present only relevant choices, for example:
+Then present only relevant actions as a **single-select structured choice** when the host supports it. In VS Code, use the native question surface such as `vscode_askQuestions` rather than printing a numbered menu. Conceptual choices may include:
 
-```text
-1. Review outcomes [READ ONLY]
-2. Review rules [READ ONLY]
-3. Review acceptance scenarios [READ ONLY]
-4. Refine identified gaps [MODIFIES DOCS or PROPOSED EXTERNAL UPDATE]
-5. Grill an unresolved decision [READ ONLY]
-6. Review full requirements/work item [READ ONLY]
-7. Approve local requirements when applicable [REQUIREMENTS GATE]
-8. Stop [NO ACTION]
-```
+- `Review outcomes` `[READ ONLY]`
+- `Review rules` `[READ ONLY]`
+- `Review acceptance scenarios` `[READ ONLY]`
+- `Refine identified gaps` `[MODIFIES DOCS or PROPOSED EXTERNAL UPDATE]`
+- `Grill an unresolved decision` `[READ ONLY]`
+- `Review full requirements/work item` `[READ ONLY]`
+- `Approve local requirements` `[REQUIREMENTS GATE]` when applicable
+- `Stop` `[NO ACTION]`
+
+Make a recommendation only when current requirement evidence or a clear engineering tradeoff supports one. If so, mark exactly one choice with the host's `recommended` indicator and briefly explain why. If there is no clear basis, show the choices without a recommendation. The selected answer, not the recommendation, controls what the session does or records.
+
+If the host has no structured choice UI, present the same relevant choices as a concise numbered text fallback and accept the number, label, or free-form intent. Do not use the numbered fallback as the normal VS Code path.
 
 ## 5. Active refinement session
 
-Once the human selects a modifying refinement option, enter a bounded continuous session:
+Once the human selects a modifying refinement choice, enter a bounded continuous session:
 
 ```text
 ask one material requirement question
@@ -139,7 +141,26 @@ ask one material requirement question
 → next material question
 ```
 
-For bounded requirement decisions such as lifecycle policy, validation behavior, destructive/reversible handling, or a small set of credible alternatives, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Keep outcome wording, workflow descriptions, acceptance intent, and other human-authored framing open-ended when predefined choices would constrain the requirement.
+For bounded requirement decisions such as lifecycle policy, validation behavior, destructive/reversible handling, or a small set of credible alternatives, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Render mutually exclusive alternatives through host-native **single-select** controls when available. Use multi-select only when the requirement genuinely permits multiple simultaneous selections. Keep `Other / specify` or free-text available when the option set may be incomplete. Keep outcome wording, workflow descriptions, acceptance intent, and other human-authored framing open-ended when predefined choices would constrain the requirement.
+
+Recommendation behavior follows the shared guide: recommend at most one option, only when evidence/tradeoffs support it; give a concise rationale; never record the recommendation as accepted until the human selects or confirms it; and honor a `no recommendation` request for that question only.
+
+Example of a supported recommendation:
+
+```text
+Decision: How should a browser-to-real-SQLite path be proven for a narrowly scoped work item?
+
+Choices:
+- Integration test against real SQLite
+- Browser smoke check through the API
+- Both
+- Other / specify
+
+Recommendation: Both
+Why: one real-SQLite integration test proves the persistence path and one browser smoke check proves the browser/API path without implying a broad end-to-end suite.
+```
+
+Treat this as advice for the human to accept, change, or replace. Do not record `Both` as a requirement until the human selects or confirms it.
 
 Do not ask after each answer whether to update.
 
@@ -162,7 +183,7 @@ Stop automatic reconciliation when an answer would:
 - require a cross-cutting architecture decision,
 - remain too ambiguous to record faithfully.
 
-Then present a small explicit choice.
+Then present a small explicit choice using the same host-native structured-choice rule. Keep the question open-ended instead when the human needs to explain or reframe the conflict in their own words.
 
 ## 7. Approval gate
 
@@ -175,7 +196,7 @@ APPROVED
 
 Human approval is explicit. Do not infer approval from review/planning/implementation.
 
-Before approval report coverage and open material decisions. Only an explicit `[REQUIREMENTS GATE]` choice may change local status to `APPROVED`.
+Before approval report coverage and open material decisions. Only an explicit `[REQUIREMENTS GATE]` choice may change local status to `APPROVED`. When the host offers structured choices, render this approval gate as a single-select action, not a numbered chat menu.
 
 External work-item status/approval follows the external team's conventions; Project Forge must not fabricate a local approval state.
 
@@ -198,7 +219,7 @@ Authority/status:
 <source and status>
 ```
 
-Then offer review, more grilling/refinement, approval when applicable, or stop.
+Then offer review, more grilling/refinement, approval when applicable, or stop using the same structured-choice-first rule.
 
 ## 9. Stop boundary
 

package/assets/generated/core/core/skills/setup/SKILL.md

@@ -138,26 +138,25 @@ If GitHub is temporarily unavailable, otherwise-ready local development remains
 
 After local readiness/profile state is understood, show the environments that this workstation can be prepared to use.
 
-Prefer a multi-select/checkbox-style interaction when the surface supports it. The conceptual shape is:
+This is an intentionally **multi-select** decision because preparing the workstation for several environments in one setup session is valid. When the host exposes structured choice UI, use its native multi-select control; in VS Code use the question surface such as `vscode_askQuestions`. Do not emulate checkboxes as ordinary chat text when native multi-select is available.
 
-```text
-SET UP THIS WORKSTATION FOR
+Conceptual choices are:
 
-[x] Local development — recommended
-[ ] Staging
-[ ] Production
-[ ] <other project-defined environment, e.g. Demo>
-[ ] Other / define another environment
-```
+- `Local development`
+- each existing project-defined environment from current topology
+- `Other / define another environment`
+
+Recommend/select `Local development` by default only because Project Forge's local-first setup policy makes it the normal initial capability and remote environments must not block local coding. Surface that rationale briefly. Do not automatically mark any additional environment recommended without project-specific evidence.
+
+If the host has no structured multi-select UI, a checkbox-like or concise textual list is the documented fallback. Free-form selection remains valid.
 
 Rules:
 
-- Local development is the recommended/default initial selection.
 - Existing named environments come from the project's current deployment topology, not a hard-coded Staging/Production list.
 - Show each environment's purpose/role compactly when the name alone is ambiguous.
-- Free-form selection remains valid when checkbox UI is unavailable.
 - Selecting an environment means **prepare this workstation for that environment**; it does not deploy the project's real application.
 - Do not force the developer to configure every environment in one session. `/setup` can be rerun later to add another capability.
+- The recorded setup scope comes from the developer's actual selections, not from any recommended/default choice.
 
 ### Topology source of truth
 
@@ -188,7 +187,7 @@ Isolation ....... <project/catalog-supported option>
 Exposure ........ <project/catalog-supported option>
 ```
 
-Provide recommended choices from the existing project topology/catalog and always allow `Other / specify` or `Not sure — recommend one` where appropriate.
+Use host-native single-select controls for bounded mutually exclusive fields such as purpose/placement/isolation/exposure when available. Keep names, targets, and other factual values open-ended. Recommend at most one option only when current topology/catalog evidence or a clear engineering tradeoff supports it; otherwise show the bounded choices without a recommendation. Always allow `Other / specify` or `Not sure — recommend one` where appropriate.
 
 Persist the approved logical environment definition before claiming it is configured. Normalize the command-facing name to the repository-supported safe slug form. Once saved, all normal environment commands use that exact name, for example:
 
@@ -263,19 +262,23 @@ If cleanup fails, report `PROOF PASSED — CLEANUP ACTION NEEDED`; do not claim
 
 For a selected **non-Production** environment, the developer's explicit `/setup` selection plus a clear preview of the disposable proof may cover the bounded proof write. Use the deterministic tool's exact authorization contract and do not add multiple ceremonial prompts.
 
-For any environment whose resolved purpose is **production**, keep one explicit consequential gate before the proof writes to it:
+For any environment whose resolved purpose is **production**, keep one explicit consequential gate before the proof writes to it. Render this gate through host-native **single-select** structured choice UI when available:
 
 ```text
 PRODUCTION ENVIRONMENT PROOF
 
 Project Forge is ready to temporarily deploy a disposable environment probe to <name>,
 verify it, and remove it. No project application or project data will be deployed.
-
-1. Run Production environment proof
-2. Verify access/readiness only
-3. Skip this environment for now
 ```
 
+Choices:
+
+- `Run Production environment proof`
+- `Verify access/readiness only`
+- `Skip this environment for now`
+
+Do not mark a choice recommended merely because a recommendation field exists. Recommend `Run Production environment proof` only when the selected setup goal and current evidence make end-to-end proof the clearly preferred next step, and explain why. Use a numbered text fallback only when structured choice UI is unavailable.
+
 A custom Production name such as `prod-east` remains Production because of its resolved purpose/classification. Never downgrade Production safety based on the literal environment string.
 
 ## 8. First real application deployment remains streamlined

package/assets/generated/core/core/skills/start-work/SKILL.md

@@ -111,16 +111,16 @@ Explain why the level was chosen.
 
 ## 4. Optional learning checkpoint
 
-For STANDARD/ELEVATED work, once requirements are ready, coaching may be offered but is never required:
+For STANDARD/ELEVATED work, once requirements are ready, coaching may be offered but is never required. When the human needs to choose, render a **single-select structured choice** through the host UI when available; in VS Code use the native question surface such as `vscode_askQuestions`.
 
-```text
-1. Continue without coaching — recommended default
-2. /coach for a short pre-build concept review
-3. /grill-me for challenge rather than teaching
-4. Stop
-```
+Relevant choices are:
 
-For LIGHT work, do not interrupt with coaching unless requested.
+- `Continue without coaching` — `RECOMMENDED` default
+- `/coach` for a short pre-build concept review
+- `/grill-me` for challenge rather than teaching
+- `Stop`
+
+Use a numbered text list only when structured choice UI is unavailable. For LIGHT work, do not interrupt with coaching unless requested.
 
 ## 5. Planning rules
 
@@ -185,6 +185,8 @@ Return:
 - requirement readiness,
 - branch state / expected short-lived branch when implementation is about to begin,
 - RECOMMENDED NEXT STEP,
-- a small numbered OPTIONS menu with action labels.
+- a small set of relevant action choices.
+
+Render mutually exclusive next actions through the host's **single-select structured choice UI** when available, following `INTERACTIVE_SESSION_GUIDE.md`. In VS Code, use the native question surface such as `vscode_askQuestions`. Make the recommended action visible when evidence supports one, include `Other / specify` or free-text only when the action set may be incomplete, and use a numbered text menu only as the no-structured-UI fallback.
 
 Do not skip an unresolved requirement/plan gate merely because implementation is technically possible. Once implementation is selected/approved, do not insert a separate ceremonial branch-creation gate when the branch setup is safe and deterministic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {