@mriekki/project-forge 2.0.0 → 2.2.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -14,8 +14,8 @@
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "80ff581ec89533f5a22bd05c65c7b67bb314c715",
-      "version": "3.0.0",
+      "commit": "d4487e07e732db4129bd092f86f6ceab36b02c15",
+      "version": "3.3.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
       "sourceRoot": "assets/generated/core",

package/assets/core/distribution.json

@@ -13,6 +13,10 @@
     {"source":"core/skills/refine-requirements/SKILL.md","destination":".github/skills/refine-requirements/SKILL.md"},
     {"source":"core/skills/start-work/SKILL.md","destination":".github/skills/start-work/SKILL.md"},
     {"source":"core/skills/setup/SKILL.md","destination":".github/skills/setup/SKILL.md"},
+    {"source":"core/skills/build/SKILL.md","destination":".github/skills/build/SKILL.md"},
+    {"source":"core/skills/run/SKILL.md","destination":".github/skills/run/SKILL.md"},
+    {"source":"core/skills/export-requirements/SKILL.md","destination":".github/skills/export-requirements/SKILL.md"},
+    {"source":"core/skills/replatform/SKILL.md","destination":".github/skills/replatform/SKILL.md"},
     {"source":"core/skills/progress/SKILL.md","destination":".github/skills/progress/SKILL.md"},
     {"source":"core/skills/next-step/SKILL.md","destination":".github/skills/next-step/SKILL.md"},
     {"source":"core/skills/deliver/SKILL.md","destination":".github/skills/deliver/SKILL.md"},
@@ -44,6 +48,9 @@
     {"source":"core/process/PROJECT_DOCUMENTATION_FRAMEWORK.md","destination":"docs/process/PROJECT_DOCUMENTATION_FRAMEWORK.md"},
     {"source":"core/process/PROJECT_FORGE_ENGINEERING_GUIDE.md","destination":"docs/project-forge/PROJECT_FORGE_ENGINEERING_GUIDE.md"},
     {"source":"core/process/SETUP_ACCEPTANCE_CHECKLIST.md","destination":"docs/process/SETUP_ACCEPTANCE_CHECKLIST.md"},
+    {"source":"core/process/OPERATION_JOURNAL.md","destination":"docs/process/OPERATION_JOURNAL.md"},
+    {"source":"core/process/PROJECT_REQUIREMENTS_EXPORT.md","destination":"docs/process/PROJECT_REQUIREMENTS_EXPORT.md"},
+    {"source":"core/process/APPLICATION_VERSIONING.md","destination":"docs/process/APPLICATION_VERSIONING.md"},
     {"source":"core/templates/PULL_REQUEST_TEMPLATE.md","destination":".github/PULL_REQUEST_TEMPLATE.md"},
     {"source":"core/templates/PRODUCT_BRIEF_TEMPLATE.md","destination":"docs/templates/PRODUCT_BRIEF_TEMPLATE.md"},
     {"source":"core/templates/FEATURE_BRIEF_TEMPLATE.md","destination":"docs/templates/FEATURE_BRIEF_TEMPLATE.md"},

package/assets/generated/ASSEMBLY.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "80ff581ec89533f5a22bd05c65c7b67bb314c715",
-      "version": "3.0.0",
+      "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,42 @@
         {
           "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",
+          "destination": ".github/skills/build/SKILL.md",
+          "sha256": "0659ad88cac5ca652eedba648d10a39ca1d51d65db638ce41b392067a3fd6128"
+        },
+        {
+          "source": "core/skills/run/SKILL.md",
+          "destination": ".github/skills/run/SKILL.md",
+          "sha256": "6bdf23f46609d1b85147347d313d7c4bf13bd8bfc91d4b782fc7a311189ffbe3"
+        },
+        {
+          "source": "core/skills/export-requirements/SKILL.md",
+          "destination": ".github/skills/export-requirements/SKILL.md",
+          "sha256": "6ef2675eafdbcc809f6fb9533ab41ff032a1f3ff4789b1d5825d27cf696d0715"
+        },
+        {
+          "source": "core/skills/replatform/SKILL.md",
+          "destination": ".github/skills/replatform/SKILL.md",
+          "sha256": "86e17bf376f395e5f5f018d8def7f5d99b9f4baef30c0b1d20f5caaac5c993c8"
         },
         {
           "source": "core/skills/progress/SKILL.md",
@@ -72,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",
@@ -122,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",
@@ -152,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",
@@ -182,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",
@@ -219,6 +239,21 @@
           "destination": "docs/process/SETUP_ACCEPTANCE_CHECKLIST.md",
           "sha256": "b5f8b39de15b464a1c80b26a6c150c6d2a363751abc05d33df4cebcad6b49d9b"
         },
+        {
+          "source": "core/process/OPERATION_JOURNAL.md",
+          "destination": "docs/process/OPERATION_JOURNAL.md",
+          "sha256": "16e2d502d7b0f923b4ea2e34bdcaaed73cdc0933fd6ef54a1278dd25f25b5140"
+        },
+        {
+          "source": "core/process/PROJECT_REQUIREMENTS_EXPORT.md",
+          "destination": "docs/process/PROJECT_REQUIREMENTS_EXPORT.md",
+          "sha256": "6ef9ecf1bb7c86b5f445554f5e630db36beee34bead2db8ff2597c148fba9c30"
+        },
+        {
+          "source": "core/process/APPLICATION_VERSIONING.md",
+          "destination": "docs/process/APPLICATION_VERSIONING.md",
+          "sha256": "846abd1085501bebf3ffd8025f875dcf2bfb3f57e67110e684c605ae11c3246b"
+        },
         {
           "source": "core/templates/PULL_REQUEST_TEMPLATE.md",
           "destination": ".github/PULL_REQUEST_TEMPLATE.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/APPLICATION_VERSIONING.md

@@ -0,0 +1,137 @@
+# Project Forge Application Versioning
+
+Every Project Forge application must implement a real runtime version identity. A static label that never changes across builds is not sufficient.
+
+## Contract
+
+Application versioning has two layers:
+
+1. **release version** — a deliberate Semantic Version such as `0.1.0` or `1.0.0`;
+2. **build identity** — automatically derived evidence that identifies the exact built artifact.
+
+The normal human-readable form is intentionally simple:
+
+```text
+v1.0.0 (build 142)
+```
+
+The machine/informational form may carry richer provenance:
+
+```text
+1.0.0+build.142.sha.a1b2c3d
+```
+
+A build record should expose equivalent fields when available:
+
+```text
+releaseVersion: 1.0.0
+buildNumber: 142
+commit: a1b2c3d
+builtAtUtc: 2026-10-21T20:15:00Z
+informationalVersion: 1.0.0+build.142.sha.a1b2c3d
+displayVersion: v1.0.0 (build 142)
+```
+
+## Release version
+
+Use Semantic Versioning (`MAJOR.MINOR.PATCH`) for the application release version.
+
+Recommended default for a new project under active development:
+
+```text
+0.1.0
+```
+
+Promote deliberately. The first accepted V1 release may become `1.0.0`; later major/minor/patch changes follow the project's release policy.
+
+The release version is expected to remain stable across multiple development builds. It must not be bumped merely to create a unique build identity.
+
+Use one stack-native authoritative source for the release version. Do not maintain unrelated duplicated constants or decorative `VERSION.md` values that can drift from the built application.
+
+## Build identity
+
+A releasable CI-built artifact must receive an automatically derived build identity.
+
+Preferred evidence:
+
+- monotonically increasing CI/build sequence number;
+- exact source commit, with a short commit acceptable for display and the full commit retained in machine evidence when practical;
+- UTC build timestamp as supplemental evidence.
+
+The canonical informational form is conceptually:
+
+```text
+<releaseVersion>+build.<buildNumber>.sha.<shortCommit>
+```
+
+A timestamp may be appended as metadata, but a date alone should not replace a sequencing value when the build system can provide a monotonic run/build number.
+
+For local developer builds where no CI build number exists, use an explicitly non-release identity such as:
+
+```text
+0.1.0+local.20261021T201500Z.sha.a1b2c3d
+```
+
+Do not invent a CI/release build number for a local build.
+
+## Runtime exposure
+
+The running application must make its effective version identity observable.
+
+For applications with a user interface, expose a concise human-readable value in an appropriate low-noise surface such as About, Settings, diagnostics, or a footer:
+
+```text
+v1.0.0 (build 142)
+```
+
+Also provide machine-readable or diagnostic evidence when the stack/application shape supports it, for example:
+
+- a version/info endpoint;
+- CLI `--version` output;
+- startup diagnostic metadata;
+- an application metadata object consumed by the UI.
+
+The display must be derived from the same build identity as the machine evidence rather than maintained as a separate hard-coded string.
+
+## Stack-specific implementation
+
+The contract is stack-independent; the implementation is not.
+
+Examples of appropriate stack-native sources include:
+
+- .NET/Blazor/ASP.NET: project/package version plus assembly/informational version metadata;
+- Node/React/Angular: package/project version plus build-time injected CI/commit metadata;
+- Java/Spring: Maven/Gradle project version plus generated build metadata/resources.
+
+These examples are implementation guidance, not a fixed technology requirement. Prefer the repository's native build/package mechanism.
+
+## Build and run helpers
+
+`/build` should report the effective release/build identity when the selected build produces or exposes it.
+
+`/run` should report the effective runtime version when the started application exposes it.
+
+Neither helper should invent version information or mutate release version state merely to make version evidence appear.
+
+## Delivery and deployment
+
+A deployable artifact should be traceable to one version identity and one source commit. Deployment evidence may record the version/build identity, but deployment must not silently rewrite it.
+
+A release tag, GitHub release, package version, container tag, or deployment label does not substitute for runtime application version evidence unless the built application actually consumes that same authoritative version metadata.
+
+## Replatforming
+
+Application versioning is a reusable engineering requirement, not a portable product requirement.
+
+`PROJECT_REQUIREMENTS.json` therefore does not need to encode stack-specific version mechanics. A replatformed project must receive the current Project Forge application-versioning contract and implement it using the target stack's native facilities.
+
+## Acceptance
+
+Application foundation is not complete until:
+
+- one authoritative release version source exists;
+- a build can derive a unique build identity without manually editing display text;
+- the source commit is traceable from build evidence;
+- a running application exposes the effective version in an appropriate human-readable form;
+- release/CI builds use a real sequencing value when the CI system provides one;
+- local builds are clearly distinguishable from release/CI builds.

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

@@ -0,0 +1,140 @@
+# Project Forge Operation Journal
+
+Project Forge uses local operation journals to preserve durable, workstation-local evidence for consequential deterministic operations without turning normal read-only guidance into noisy state.
+
+## Purpose
+
+An operation journal answers:
+
+- what deterministic operation ran;
+- when it started and finished;
+- which workspace/platform/provenance it used;
+- which bounded steps ran and their outcomes;
+- where a failure occurred;
+- what final status was reached.
+
+The journal is diagnostic evidence. It is not a second workflow database and it does not replace Git, GitHub, CI, deployment state, or human acceptance.
+
+## Location
+
+Store local journals under the ignored Project Forge cache:
+
+```text
+.project-forge/
+  logs/
+    <operation>/
+      <timestamp>-<run-id>.log
+      latest.log
+```
+
+Examples:
+
+```text
+.project-forge/logs/setup/2026-10-20T190523-0700-18432.log
+.project-forge/logs/build/...
+.project-forge/logs/run/...
+.project-forge/logs/project-forge-update/...
+.project-forge/logs/deployment-readiness/...
+.project-forge/logs/deploy/...
+.project-forge/logs/tear-down/...
+```
+
+`latest.log` may be a copied summary/current run for convenience. Implementations must not depend on symlink support.
+
+Operation journals are workstation-local and must remain ignored by Git. They are never part of `CORE_BASELINE.json`, `PROJECT_FORGE_BASELINE.json`, or application provenance.
+
+## Operations that should journal
+
+Journal deterministic operations when durable local diagnostics materially help:
+
+- `/setup` and repository-local setup/doctor execution;
+- `/build` when build diagnostics/artifact evidence are useful;
+- `/run` as a concise startup/health receipt when useful, not as an unbounded application log sink;
+- `/project-forge-update` apply/verification work;
+- `/developer-env-mode` when it mutates or converges local runtime state;
+- `/deployment-readiness` when it performs preparation or repair;
+- environment proof operations;
+- `/deploy` and `/tear-down`;
+- other bounded deterministic operations that mutate workstation or remote environment state.
+
+`/deliver` may write a concise local receipt, but Git commits, PRs, CI, and merge history remain its authoritative durable evidence.
+
+Read-only orientation normally does **not** create a journal:
+
+- `/progress`;
+- `/next-step`;
+- `/wait-what`;
+- read-only documentation/learning navigation;
+- read-only status checks unless a caller explicitly requests troubleshooting evidence.
+
+Remote GitHub Actions already retain their own workflow logs. Do not duplicate complete remote logs locally; record only the local request/provenance/result receipt when useful.
+
+## Minimum record
+
+A journal should capture, when available:
+
+```text
+operation
+run identifier
+started/finished timestamps
+workspace root or project identity
+platform/architecture
+relevant Project Forge/Core/Bootstrap/Deployment provenance
+step name
+step status
+resolved tool/version evidence
+sanitized command identity
+exit code
+sanitized failure summary
+final status
+```
+
+For `/build`, include the requested target and explicit artifact/output paths when the repository build contract establishes them.
+
+For `/run`, record only bounded startup evidence such as target, command identity, process/startup result, established local endpoint/health result, and stop guidance. Do not continuously tee long-running application output into the Project Forge journal.
+
+Prefer stable event names and compact machine-readable fields inside a human-readable `.log`. JSON Lines is acceptable when the implementation already uses structured events.
+
+At completion, report the journal path to the developer when the operation was consequential or when diagnostics were produced.
+
+## Security and privacy boundary
+
+Operation journals are diagnostic artifacts, not raw transcripts.
+
+Never log:
+
+- passwords, PATs, API keys, access tokens, private SSH keys, or secret values;
+- credential-manager contents;
+- full process environment dumps;
+- request/response bodies that may contain credentials;
+- arbitrary stdin or secure-prompt contents;
+- known-host private material or mutable application data merely for convenience.
+
+Prefer allowlisted structured fields over blind stdout/stderr capture.
+
+When command arguments or error text may contain secrets, redact before writing. Implementations should log a command identity such as executable + safe arguments, step name, return code, and a bounded sanitized failure summary rather than blindly teeing every subprocess byte.
+
+A local journal must not weaken an existing secure prompt, credential boundary, or Human-in-the-Loop gate.
+
+## Lifecycle
+
+For a mutating deterministic operation:
+
+1. create the journal before the first material mutation;
+2. record operation/provenance preflight;
+3. append bounded step outcomes as work proceeds;
+4. flush useful failure evidence before returning/raising;
+5. record one final state such as `READY`, `SUCCESS`, `DEFERRED`, `BLOCKED`, `FAILED`, or a domain-specific equivalent;
+6. refresh `latest.log` only after the run has a coherent record.
+
+A failed operation keeps its timestamped journal. Do not erase failure evidence merely because a later retry succeeds.
+
+## Retention
+
+Journals are disposable local diagnostics. Project Forge may prune old logs using a conservative size/count policy, but must preserve the current run while it is active and should retain enough recent history to diagnose repeated failures.
+
+Do not silently upload operation journals to GitHub, ChatGPT, telemetry, or another machine. A developer may explicitly choose to share a relevant sanitized excerpt when troubleshooting.
+
+## Relationship to human acceptance
+
+A successful journal entry is machine evidence only. It never marks editor/workspace acceptance, meaningful-diff acceptance, merge authorization, release publication, or production deployment approval on the human's behalf.