@mriekki/project-forge 2.0.0 → 2.2.0

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/replatform/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: replatform
+description: "Create a new implementation proposal from approved PROJECT_REQUIREMENTS.json and a requested target stack without rewriting the source project in place."
+argument-hint: "<target-stack-or-recipe>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Replatform
+
+`/replatform` creates a new implementation proposal for the same product/system intent using a different technology stack.
+
+It never rewrites the source application in place.
+
+## Required input
+
+Use only the canonical portable export:
+
+```text
+PROJECT_REQUIREMENTS.json
+```
+
+The file must be `state: "approved"`. Do not accept alternate/legacy requirements-export filenames or infer approval from file existence.
+
+If the export is missing or stale relative to material source-requirement changes, use `/export-requirements` first.
+
+## Target
+
+The invocation supplies a target stack or current Bootstrap recipe, for example:
+
+```text
+/replatform angular java
+/replatform java-angular-sqlite
+/replatform blazor sqlite
+```
+
+Resolve support against the current canonical Project Forge Bootstrap catalog. General model knowledge may explain an uncataloged technology, but label it `CATALOG GAP` and do not fabricate Bootstrap automation/support.
+
+## Output boundary
+
+The operation produces a new `PROJECT_BOOTSTRAP.json` proposal with `state: "review"` for a new target repository.
+
+It must record derivation provenance back to the approved requirements export/source repository and identify the selected current Bootstrap catalog/protocol and Project Forge package provenance.
+
+Do not generate application source or mutate the target repository until the normal Bootstrap manifest review/approval gate is complete.
+
+## Reconciliation rules
+
+Preserve from the approved requirements export:
+
+- product problem/goals/users/outcomes;
+- Product Feature intent and target maturity;
+- approved functional/domain requirements and acceptance criteria;
+- domain concepts, relationships, invariants, lifecycle/state semantics, and business rules;
+- portable security/privacy/reliability/data constraints;
+- portable design, accessibility, responsive, and interaction intent;
+- roadmap maturity (`committed`, `planned`, `directional`);
+- explicitly preserved learning intent.
+
+Re-derive for the requested stack:
+
+- Engineering Enablers;
+- framework/application shell work;
+- implementation architecture/topology;
+- persistence/ORM implementation;
+- API/client implementation choices;
+- build/run/test commands and package tooling;
+- stack-specific ADRs;
+- CI implementation details;
+- deployment mechanics that depend on the new architecture.
+
+Do not automatically preserve source Engineering Enabler IDs. Product Feature IDs may remain traceable when the semantic Feature is unchanged; record source IDs even when the new implementation re-slices or renumbers work.
+
+## New-repository rule
+
+Replatforming requires a new target repository identity. The source repository is read-only evidence.
+
+Never:
+
+- overwrite the source repository;
+- replace its `PROJECT_BOOTSTRAP.json`;
+- delete or rewrite source implementation history;
+- copy source application code by default;
+- copy secrets, production data, credentials, machine bindings, or execution evidence.
+
+## Bootstrap execution
+
+Use the current canonical Bootstrap replatform tooling when available. The expected deterministic boundary is:
+
+```text
+approved PROJECT_REQUIREMENTS.json
++ requested current catalog recipe/stack
++ target repository identity
+→ PROJECT_BOOTSTRAP.json state=review
+```
+
+If canonical Bootstrap replatform tooling/current catalog evidence is unavailable in the current environment, stop with `REPLATFORM HANDOFF REQUIRED`. Do not invent a manifest from stale remembered catalog facts.
+
+## Human gate
+
+Before generation, summarize at minimum:
+
+```text
+SOURCE REQUIREMENTS
+source repository/commit
+portable requirements export provenance
+
+PRESERVED
+product/features/domain/UX/cross-cutting intent
+roadmap maturity
+
+RE-DERIVED
+stack-specific architecture and Engineering Enablers
+
+TARGET STACK
+resolved current catalog recipe and support state
+
+OUTPUT
+PROJECT_BOOTSTRAP.json — REVIEW
+```
+
+Then use the normal material Bootstrap manifest approval gate. Approval of replatform intent is not approval to merge, release, or deploy the resulting implementation.

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

@@ -0,0 +1,75 @@
+---
+name: run
+description: "Run the current project locally through its repository-owned runtime command without conflating local execution with deployment."
+argument-hint: "[target|all]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Run
+
+`/run` is the normal convenience entry point for starting the project locally. It resolves and delegates to repository-owned runtime commands rather than requiring the developer to remember framework-specific launch syntax.
+
+## Contract
+
+Invoking `/run` authorizes one bounded local start attempt for the requested target. It does not authorize setup, source edits, deployment, release publication, Production access, or persistent background services outside the repository's normal local-development contract.
+
+Resolve the local runtime command from current repository evidence in this order:
+
+1. an explicit repository-owned run/dev wrapper or documented command;
+2. an explicit package/task script whose purpose is local run/dev;
+3. an unambiguous ecosystem-native local entry point already present in the repository.
+
+Do not guess. If the repository has multiple independent runtimes and no documented default, require a target such as `/run web`, `/run api`, or `/run all`.
+
+## Preconditions
+
+Before starting:
+
+- identify repository root and current Git state;
+- inspect `PROJECT_BOOTSTRAP.json` and scaffold/readiness evidence when present;
+- verify the selected runtime entry point exists;
+- inspect any documented local ports/health endpoints;
+- do not create an intentionally deferred scaffold merely to make `/run` succeed.
+
+If runtime source is intentionally deferred or absent, return `RUN NOT AVAILABLE` and identify the owning work item or missing marker when repository evidence provides it.
+
+If workstation tools or dependencies are missing, recommend `/setup` instead of silently installing them.
+
+## Execution
+
+Start the process in an observable developer-controlled terminal/process surface. Do not hide a long-running application in an unexplained background process.
+
+Report:
+
+- target;
+- resolved command identity;
+- process/startup result;
+- effective application release/build identity when the running application exposes it;
+- local URL/port or health evidence only when repository/runtime evidence establishes it;
+- how to stop the process.
+
+When `/run all` is explicitly supported, start only the repository-defined set of local components and make each process/endpoint visible.
+
+When the project implements `docs/process/APPLICATION_VERSIONING.md`, prefer runtime-observed version evidence over a source-file guess. Do not synthesize a build number or claim that a static source label proves the running artifact's identity.
+
+## Operation journal
+
+`/run` may write a concise sanitized startup receipt under `.project-forge/logs/run/` following `docs/process/OPERATION_JOURNAL.md`.
+
+Record startup command identity, target, timestamps, startup/health result, observed application version/build identity, and endpoint when established. Do not duplicate or continuously capture unbounded application stdout/stderr into the Project Forge journal.
+
+## Deployment boundary
+
+`/run` is not `/deploy local`.
+
+It must not:
+
+- mutate remote environments;
+- publish images/packages/releases;
+- change deployment bindings;
+- infer Production configuration;
+- bump or rewrite release version state;
+- stage, commit, push, merge, or clean branches.
+
+A successful `/run` proves only that the requested local runtime started with the evidence observed in that session.

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.0.0",
+  "version": "2.2.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {