@mriekki/project-forge 2.1.0 → 3.0.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "fd071b9516cb40093f30be41ab695139eb16bb4c",
+      "commit": "17a09fc913a12902c4a9172e53bc70d421f5b0d5",
       "version": "3.3.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -23,7 +23,7 @@
     },
     "deployment": {
       "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "54fcc256c525ea8762568043c3900f4d2d36c816",
+      "commit": "0974f36bcb5062c4becb7c5c4e0fbc3e629ad4a9",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/deployment/distribution.json

@@ -49,6 +49,6 @@
     {"source": "docs/ENVIRONMENT_PROOF.md", "destination": "docs/project-forge/ENVIRONMENT_PROOF.md"},
     {"source": "docs/images/developer-environment-journey.svg", "destination": "docs/project-forge/images/developer-environment-journey.svg"},
     {"source": "docs/images/personal-environment-architecture.svg", "destination": "docs/project-forge/images/personal-environment-architecture.svg"},
-    {"source": "docs/images/poc-environment-model.svg", "destination": "docs/project-forge/images/poc-environment-model.svg"}
+    {"source": "docs/images/project-environment-model.svg", "destination": "docs/project-forge/images/project-environment-model.svg"}
   ]
 }

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "fd071b9516cb40093f30be41ab695139eb16bb4c",
+      "commit": "17a09fc913a12902c4a9172e53bc70d421f5b0d5",
       "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": "60dcb93e98f6f00177e9e2d406c55f15bd59ebf8607c3f79ae464fe7c00616b6"
         },
         {
           "source": "core/skills/build/SKILL.md",
@@ -87,37 +87,37 @@
         {
           "source": "core/skills/progress/SKILL.md",
           "destination": ".github/skills/progress/SKILL.md",
-          "sha256": "7c9524859f4683feee2e8fac33ef3aa24f2b7b38099a37c3b65eb746aaba7391"
+          "sha256": "9b0ba914529e6bd91ad5fd7a30f666884c1687b35b847bfe77ed745c50f0fd12"
         },
         {
           "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",
@@ -137,17 +137,17 @@
         {
           "source": "core/skills/deployment-readiness/SKILL.md",
           "destination": ".github/skills/deployment-readiness/SKILL.md",
-          "sha256": "846ddacc3f9acaecfce3ba62a6c1eb01149f1afd1013e307a81dc65e1351cbc4"
+          "sha256": "82eaf37f8acc4e3d69871a02ad38ab9bf94caccaa0b3a40784dbb622621e112c"
         },
         {
           "source": "core/skills/deploy/SKILL.md",
           "destination": ".github/skills/deploy/SKILL.md",
-          "sha256": "7bacd366014bf8c890328ec2b78412a39a0abff2f6b44dd53ca129102a7a30c8"
+          "sha256": "8296d5cdd166dc5e0125df5d8ebc83d901a04f71caad8563ec67e9d02761955a"
         },
         {
           "source": "core/skills/tear-down/SKILL.md",
           "destination": ".github/skills/tear-down/SKILL.md",
-          "sha256": "5fcda93f4a0d1eca76a8a753f340fcb1799bddfe515324493e7d910f1c2253a3"
+          "sha256": "7565b5600af2883abfc47bac29abfd056cfa81536c52408b07da82f696b335b8"
         },
         {
           "source": "core/skills/coach/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",
@@ -192,7 +192,7 @@
         {
           "source": "core/process/DEPLOYMENT_ENABLEMENT.md",
           "destination": "docs/process/DEPLOYMENT_ENABLEMENT.md",
-          "sha256": "987f6e68a2ab58d23388127fae2318b385ef86de389fc616c1e40b48c0ff3b07"
+          "sha256": "fa4f0bf3929d7d07b0061191232d39a7d03ae5e1e334e2aeafd27bad83b845fc"
         },
         {
           "source": "core/process/HUMAN_GATES.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",
@@ -227,12 +227,12 @@
         {
           "source": "core/process/PROJECT_DOCUMENTATION_FRAMEWORK.md",
           "destination": "docs/process/PROJECT_DOCUMENTATION_FRAMEWORK.md",
-          "sha256": "3e77e85e7c8d466f8f3fbe588569cb6f0d9e1ca52e81f1803fae4481c8ea93d3"
+          "sha256": "bcb9f73dad1490ac5b45fe1bac931d488112727bad537534d8b9ffd5b115d84b"
         },
         {
           "source": "core/process/PROJECT_FORGE_ENGINEERING_GUIDE.md",
           "destination": "docs/project-forge/PROJECT_FORGE_ENGINEERING_GUIDE.md",
-          "sha256": "431eb3af7593f5f79f74ffdd306f56b5249a632c480fd6c3e5f0223161d376d9"
+          "sha256": "c09e0f088682302751d2f98629959cc4dab5e8a441ba19fb3417468e3895cc20"
         },
         {
           "source": "core/process/SETUP_ACCEPTANCE_CHECKLIST.md",
@@ -348,7 +348,7 @@
     },
     "deployment": {
       "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "54fcc256c525ea8762568043c3900f4d2d36c816",
+      "commit": "0974f36bcb5062c4becb7c5c4e0fbc3e629ad4a9",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -404,7 +404,7 @@
         {
           "source": "src/project_forge_deployment/cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/cli.py",
-          "sha256": "594915682f6b4e60bc6b63a43c5847d557f1fbfd3c22a2623e5bb572b6ab4dda"
+          "sha256": "3c3e7d4fadeccc1b8a7691c1a213250790fb728400914894c0d4e70a1ec91cc7"
         },
         {
           "source": "src/project_forge_deployment/doctor.py",
@@ -414,7 +414,7 @@
         {
           "source": "src/project_forge_deployment/entrypoint.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/entrypoint.py",
-          "sha256": "8f27177c65121a1e83b6a534ac18fc6474e138e0953caf2204ede95eb724cba9"
+          "sha256": "94c5eeff4ef684a4665909f7710d95fb4f65c118a71f60782b048697d6a495dd"
         },
         {
           "source": "src/project_forge_deployment/environment_cli.py",
@@ -424,7 +424,7 @@
         {
           "source": "src/project_forge_deployment/environment_probe.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/environment_probe.py",
-          "sha256": "6b0b9be56cf7ab4e7683755bc990c7c24a66951a3d9179862694ee2ff74e67ae"
+          "sha256": "3971264b425c9eb49845a48a54aea849ef35b36b86b13017c0946d3b90e9d707"
         },
         {
           "source": "src/project_forge_deployment/errors.py",
@@ -499,7 +499,7 @@
         {
           "source": "src/project_forge_deployment/route_registry.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/route_registry.py",
-          "sha256": "8c19da6790fac66d0cb8fe099fb09c026966a6e5952df58bd936ce03a72f1928"
+          "sha256": "ea08753878e9e6b59a8986aac7e40e40f66651cc704fff50842badf956705744"
         },
         {
           "source": "src/project_forge_deployment/route_registry_remote.py",
@@ -539,17 +539,17 @@
         {
           "source": "src/project_forge_deployment/teardown.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/teardown.py",
-          "sha256": "114b6e29725caaf105e67b5407de9a21c4ae9a9bfdc965bd4a0f1e91c316d011"
+          "sha256": "08215b8b5fa87ca8abf96f10f38aca0207840bd1b1faf4c2c53cb691caf20a72"
         },
         {
           "source": "src/project_forge_deployment/teardown_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/teardown_cli.py",
-          "sha256": "e4f436a0f1bbbfcff4940c3f4b961b7acdb94f6e3e44bc0e8df10a46b13b8840"
+          "sha256": "214987895cde77648b5274042f1c21557046c3bf76224bfdd415ea34fec3d873"
         },
         {
           "source": "src/project_forge_deployment/teardown_remote.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/teardown_remote.py",
-          "sha256": "d4685f41d380047c69345bf689122d7c372441db24225b5fc218a76e1ec653c6"
+          "sha256": "ad764f5a67c43f81b4973dd5639b2c28b23ae883a85e5ae29efc14dad506e88e"
         },
         {
           "source": "src/project_forge_deployment/trust.py",
@@ -559,22 +559,22 @@
         {
           "source": "docs/DEVELOPER_ENVIRONMENTS.md",
           "destination": "docs/project-forge/DEVELOPER_ENVIRONMENTS.md",
-          "sha256": "32e0005102825d2da1a5b960b80b8485903337dc451f12e12bc93078611859f9"
+          "sha256": "e818931055044f6158ffe321303a5cbcd2f58724430d51e87c1688e1f71a8fbc"
         },
         {
           "source": "docs/WORKSPACE_INSTANCES.md",
           "destination": "docs/project-forge/WORKSPACE_INSTANCES.md",
-          "sha256": "8831f2c0bc7a5450464aafbe83e55825077469c2a24a4698a76b830446777cda"
+          "sha256": "43da263213d3822308d4a9bc57b53119e8b0abdc92e14afb354e88dedd2b0706"
         },
         {
           "source": "docs/ENVIRONMENT_PROOF.md",
           "destination": "docs/project-forge/ENVIRONMENT_PROOF.md",
-          "sha256": "27bd5751f071c0851655540e37c7cb160495a3458a98409221bfd14c4ddcb061"
+          "sha256": "d139ec1691d073e845a679edf45cb01c971a40b3ccc31404efb8c1e81e481ea5"
         },
         {
           "source": "docs/images/developer-environment-journey.svg",
           "destination": "docs/project-forge/images/developer-environment-journey.svg",
-          "sha256": "5b9e481015e1460afc66945740146da8390590dac307ffdc4ee62988cf001733"
+          "sha256": "f799027ee52105f482231998ecda9bf6f6e05590f131ec0c7d04cd8d27b3ca51"
         },
         {
           "source": "docs/images/personal-environment-architecture.svg",
@@ -582,9 +582,9 @@
           "sha256": "a2d5a4a6b52eaa451bb3b28eb9a856a30750b00e9f1c5932c645bdc8e96f935f"
         },
         {
-          "source": "docs/images/poc-environment-model.svg",
-          "destination": "docs/project-forge/images/poc-environment-model.svg",
-          "sha256": "7f2bc72ca7cad77e0de7673453e7a8508d1bc0e0628dc2777522f6e737bd4cef"
+          "source": "docs/images/project-environment-model.svg",
+          "destination": "docs/project-forge/images/project-environment-model.svg",
+          "sha256": "357896c40ff2c7a93bf77811af61d2559103d2e386a5fd887c7041d016114b10"
         }
       ]
     }

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/DEPLOYMENT_ENABLEMENT.md

@@ -104,7 +104,7 @@ Keep their targetable scope, runtime/container, route, data, readiness evidence,
 TOPOLOGY NOTE
 
 Staging and Production are logically isolated but share one physical
-failure domain. This may fit POC cost/learning goals, but it does not
+failure domain. This may fit Project cost/learning goals, but it does not
 demonstrate host-level Production isolation.
 ```
 

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/process/PROJECT_DOCUMENTATION_FRAMEWORK.md

@@ -15,7 +15,7 @@ Project Forge project documentation is a small, evidence-aware engineering syste
 
 ## Canonical shape
 
-Greenfield POCs should normally converge on:
+Greenfield Projects should normally converge on:
 
 ```text
 README.md
@@ -82,7 +82,7 @@ Keep it short. It should answer:
 
 `PROJECT_BRIEF.md` is the integrated project briefing and navigation surface. It may summarize approved product scope, stack, environments, initial work items, learning goals, and important documentation links.
 
-It is **not** a second requirements authority. In a normal Project Forge greenfield POC:
+It is **not** a second requirements authority. In a normal Project Forge greenfield Project:
 
 - `docs/product/PRODUCT_BRIEF.md` remains product authority;
 - approved work-item briefs/requirements remain work-item authority;
@@ -143,7 +143,7 @@ Recommended schema:
 {
   "schemaVersion": 1,
   "site": {
-    "title": "Example POC",
+    "title": "Example Project",
     "entry": "PROJECT_BRIEF.md"
   },
   "documents": [

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

@@ -31,7 +31,7 @@ The platform lowers the friction of starting a personal project while preserving
 | Choice | Select a technology direction based on project needs or learning goals, with explicit support-state signals rather than hidden assumptions. |
 | Discipline | Use a Project Forge workflow with bounded implementation, review, CI evidence, and meaningful human acceptance points. |
 | Learning | Build understanding alongside code through work-item guides, code walkthroughs, learning review, and targeted coaching. |
-| Realism | Exercise containerization, source control, CI, releases, environment isolation, and deployment tradeoffs without pretending every POC needs dedicated Staging/Production computers. |
+| Realism | Exercise containerization, source control, CI, releases, environment isolation, and deployment tradeoffs without pretending every Project needs dedicated Staging/Production computers. |
 | Repeatability | Create self-contained generated repositories with explicit provenance and controlled platform updates. |
 
 ### Why this is different from “generate me an app”
@@ -65,23 +65,23 @@ Clear ownership boundaries keep process, package transport, orchestration, deplo
 
 ```mermaid
 flowchart TB
-  BOOT[POC Bootstrap<br/>Discovery, catalog, manifests,<br/>deterministic generation] --> POC[Generated POC<br/>self-contained consumer]
-  CORE[Agentic Core<br/>Workflow, agents, skills,<br/>HITL gates, learning] --> POC
-  PLATFORM[Project Forge Platform / @mriekki/project-forge<br/>Exact accepted reusable components] --> POC
-  CONTROL[Control Plane<br/>GitHub App orchestration<br/>and safe publication] --> POC
-  DEPLOY[Deployment Kit<br/>Workstation + remote-target mechanics] --> POC
+  BOOT[Project Bootstrap<br/>Discovery, catalog, manifests,<br/>deterministic generation] --> PROJECT[Generated Project<br/>self-contained consumer]
+  CORE[Agentic Core<br/>Workflow, agents, skills,<br/>HITL gates, learning] --> PROJECT
+  PLATFORM[Project Forge Platform / @mriekki/project-forge<br/>Exact accepted reusable components] --> PROJECT
+  CONTROL[Control Plane<br/>GitHub App orchestration<br/>and safe publication] --> PROJECT
+  DEPLOY[Deployment Kit<br/>Workstation + remote-target mechanics] --> PROJECT
 ```
 
 | Layer | Responsibility |
 | --- | --- |
-| POC Bootstrap | Discovery protocol, catalog/support states, approved `PROJECT_BOOTSTRAP.json`, deployment topology intent, deterministic generation, setup/readiness helpers, work-item materialization. |
+| Project Bootstrap | Discovery protocol, catalog/support states, approved `PROJECT_BOOTSTRAP.json`, deployment topology intent, deterministic generation, setup/readiness helpers, work-item materialization. |
 | Agentic Core | Reusable workflow behavior, agents/skills, Human-in-the-Loop gates, review/delivery semantics, learning flows, topology-aware deployment orchestration. |
 | Project Forge Platform | Consumer-facing `@mriekki/project-forge` package that assembles exact accepted reusable components and records provenance. |
 | Control Plane | GitHub App orchestration for target validation, short-lived scoped credentials, deterministic generation, and safe publication. |
 | Deployment Kit | Reusable one-workstation loopback-container runtime plus strict remote target/access, Ubuntu/Docker/Caddy routing, persistence, and scoped tear-down mechanics. Managed hosting remains adapter-specific rather than generic implied support. |
-| Generated POC | Owns product scope, architecture, code/tests, work items, CI evidence, logical environment/topology facts, concrete deployment bindings, accepted baselines, and implementation history. |
+| Generated Project | Owns product scope, architecture, code/tests, work items, CI evidence, logical environment/topology facts, concrete deployment bindings, accepted baselines, and implementation history. |
 
-**Architectural outcome:** a generated POC remains usable on its own. Normal development and deployment do not depend on sibling clones of the platform repositories.
+**Architectural outcome:** a generated Project remains usable on its own. Normal development and deployment do not depend on sibling clones of the platform repositories.
 
 ---
 
@@ -191,7 +191,7 @@ flowchart LR
 
 ### Use AI to increase capability, not only throughput
 
-The system treats a personal POC as both a software deliverable and a deliberate learning vehicle — without turning learning into a release gate.
+The system treats a personal Project as both a software deliverable and a deliberate learning vehicle — without turning learning into a release gate.
 
 - **Embedded context** — work-item Implementation & Learning Guides connect engineering outcomes to concepts, reasoning prompts, things to notice, hands-on opportunities, and learning evidence.
 - **Code walkthrough** — `/code-walkthrough` explains the actual implementation, architecture boundaries, control flow, and important tradeoffs after the work exists.
@@ -271,7 +271,7 @@ The original briefing used Family Meal Planner v3 to demonstrate re-baselining a
 - **Selected stack:** `dotnet-react-sqlite` recipe with partial support; generic scaffold intentionally deferred rather than allowed to overwrite mature architecture decisions.
 - **First work item:** EN-001 — Application Foundation / Walking Skeleton: prove React, ASP.NET, browser-to-API, SQLite through approved layers, dependency injection, health/system info, Compose, and CI.
 - **App-specific deployment model in that reference consumer:** Production and Staging are distinct Ubuntu environments over trusted-LAN SSH with separate target/access contracts and no cross-environment fallback.
-- **Learning goal:** use the project as a hands-on software-engineering POC and build enough understanding to review and explain the system rather than only accept generated implementation.
+- **Learning goal:** use the project as a hands-on software-engineering Project and build enough understanding to review and explain the system rather than only accept generated implementation.
 - **Lifecycle point in the original briefing:** the v3 repository had an approved seed manifest and was at the GitHub-first generation handoff when the original briefings were prepared.
 
 The FMP topology is an **example consumer choice**, not a reusable requirement for other Project Forge users.
@@ -287,13 +287,13 @@ The FMP topology is an **example consumer choice**, not a reusable requirement f
 The strongest claim is not that AI can do everything. It is that a reusable operating model can make disciplined engineering the lowest-friction way to explore an idea.
 
 - **Not “any stack, fully automated.”** Technology choice is broad; Bootstrap automation is claimed only where the live catalog supports it.
-- **Not “every POC needs servers.”** One-machine local/demo and explicitly deferred deployment are valid outcomes.
+- **Not “every Project needs servers.”** One-machine local/demo and explicitly deferred deployment are valid outcomes.
 - **Not generic cloud support.** A plausible provider is not supported until a provider adapter is cataloged, implemented, and proven.
 - **Not autonomous Production.** Merge, CI, or release publication never implies Production deployment. Production and destructive operations remain separately gated regardless of placement.
 - **Not model-dependent.** Repository-local workflow assets define behavior; Core does not rely on one fixed AI model to preserve the engineering process.
-- **Not hidden regeneration.** Generated POCs are self-contained consumers. Reusable updates go through controlled package/baseline paths rather than silent wholesale regeneration.
+- **Not hidden regeneration.** Generated Projects are self-contained consumers. Reusable updates go through controlled package/baseline paths rather than silent wholesale regeneration.
 - **AI drift is bounded.** Repository protocol, catalog, baselines, and project-owned artifacts outrank conversational inference about project state.
-- **Still a POC platform.** This is a disciplined engineering POC platform with strong foundations and explicit remaining proof/maturity work — not a finished enterprise developer platform.
+- **Still a Project platform.** This is a disciplined engineering Project platform with strong foundations and explicit remaining proof/maturity work — not a finished enterprise developer platform.
 
 ### Strategic takeaway
 

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