@mriekki/project-forge 4.4.1 → 4.5.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,8 +13,7 @@
   },
   "components": {
     "core": {
-      "repository": "mriekki/project-forge-core",
-      "commit": "45139179c3d10ebd89702ac3aedec231364d8a34",
+      "revision": "d106b1834a8c44bdae0b16e4af5d8dab0711a120",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -22,8 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "880a911bc87e38c74ca4b336c9563a6f026ac3b4",
+      "revision": "880a911bc87e38c74ca4b336c9563a6f026ac3b4",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,10 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "components": {
     "core": {
-      "repository": "mriekki/project-forge-core",
-      "commit": "45139179c3d10ebd89702ac3aedec231364d8a34",
+      "revision": "d106b1834a8c44bdae0b16e4af5d8dab0711a120",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -22,7 +21,7 @@
         {
           "source": "core/instructions/project-forge-workflow.instructions.md",
           "destination": ".github/instructions/project-forge-workflow.instructions.md",
-          "sha256": "85568ba56681831e34c63aa14f91702522a451e8b2fa883da631d609440d7a7c"
+          "sha256": "13379a56c65921756cdae8e1d2d711c3321b9d899b5d96a81dbf51ecaa9ce022"
         },
         {
           "source": "core/instructions/project-forge-docs.instructions.md",
@@ -42,7 +41,7 @@
         {
           "source": "core/skills/refine-requirements/SKILL.md",
           "destination": ".github/skills/refine-requirements/SKILL.md",
-          "sha256": "ee5085ac6bbf8fb33ab5f6b52e0ac954c164fd3ea51f90965c9bde86adc88def"
+          "sha256": "9e76b9c3700a00af8852928d4e6bf1aeca9a24c6cc8fc9b2f1873e0198b63962"
         },
         {
           "source": "core/skills/start-work/SKILL.md",
@@ -187,7 +186,7 @@
         {
           "source": "core/process/INTERACTIVE_SESSION_GUIDE.md",
           "destination": "docs/process/INTERACTIVE_SESSION_GUIDE.md",
-          "sha256": "8cd74fbd7433969923299849eb89bdd774fd4af1b9694639f0b9871a1047cacf"
+          "sha256": "08df5212fc6d08e46d3121dad3d076e05baa71b046a7e360a201b18916b7e574"
         },
         {
           "source": "core/process/COACHING_GUIDE.md",
@@ -327,8 +326,7 @@
       ]
     },
     "deployment": {
-      "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "880a911bc87e38c74ca4b336c9563a6f026ac3b4",
+      "revision": "880a911bc87e38c74ca4b336c9563a6f026ac3b4",
       "distribution": "greenfield-project",
       "files": [
         {

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

@@ -20,9 +20,9 @@ For implementation, establish the repository-appropriate short-lived work branch
 
 Continuous modes such as `/grill-me`, `/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. 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.
+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 or lettered 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.
+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. When the host does not expose recommendation metadata, append `[RECOMMENDED]` to exactly one option label and keep the rationale visible. A default/preselected option may match the recommendation, but a default alone must never communicate advice or human approval. If no option is clearly better, do not mark any option recommended and do not use a default that implies a preference. 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.
 

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

@@ -51,16 +51,18 @@ A recommendation is optional advice, not a required field and not an accepted de
 
 - 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;
+- when the host does not expose recommendation metadata, append `[RECOMMENDED]` to exactly one option label and keep the concise rationale visible in the prompt or option description;
+- a default/preselected value may match the recommended option, but a default alone must never communicate that an option is recommended or human-approved;
 - 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**;
+- when no option is clearly better, present the choices with **no recommendation** and do not use a default that implies a preference;
 - 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.
+When the host has no structured question UI, use a concise textual fallback. A numbered or lettered list is acceptable **only as this fallback**; keep the same labels/recommendation/consequence tags, including `[RECOMMENDED]` when one option is evidence-backed, and accept the number/letter, 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:
 

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

@@ -124,9 +124,9 @@ Then present only relevant actions as a **single-select structured choice** when
 - `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.
+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 when that metadata exists; otherwise append `[RECOMMENDED]` to exactly one option label. Briefly explain why in the option description or surrounding prompt. A default/preselected value may match the recommendation, but a default alone must never communicate advice or approval. If there is no clear basis, show the choices without a recommendation and without a preference-implying default. 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.
+If the host has no structured choice UI, present the same relevant choices as a concise numbered or lettered text fallback, preserve `[RECOMMENDED]` on the evidence-backed option when applicable, and accept the number/letter, label, or free-form intent. Do not use the text fallback as the normal VS Code path.
 
 ## 5. Active refinement session
 
@@ -143,7 +143,7 @@ ask one material requirement 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`. 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.
+Recommendation behavior follows the shared guide: recommend at most one option, only when evidence/tradeoffs support it; make the recommendation visibly distinguishable through native metadata or `[RECOMMENDED]`; 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:
 
@@ -153,11 +153,8 @@ Decision: How should a browser-to-real-SQLite path be proven for a narrowly scop
 Choices:
 - Integration test against real SQLite
 - Browser smoke check through the API
-- Both
+- Both [RECOMMENDED] — proves persistence and browser/API paths without implying a broad end-to-end suite
 - 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.

package/package.json

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

package/src/engine.mjs

@@ -54,6 +54,12 @@ function baselineMap(baseline, filename) {
   return map;
 }
 
+function componentRevision(component) {
+  const revision = component.revision ?? component.commit;
+  if (typeof revision !== 'string' || !/^[0-9a-f]{40}$/i.test(revision)) throw new Error('Component revision must be an exact 40-character Git revision');
+  return revision.toLowerCase();
+}
+
 export function componentEntries(packageData, componentId) {
   const component = packageData.assets.components[componentId];
   if (!component) throw new Error(`Package does not define component ${componentId}`);
@@ -95,22 +101,27 @@ function classifyDesired(componentId, src, dst, baselineItem) {
   return { state: 'CONFLICT', desiredHash, currentHash };
 }
 
-function coreMetadataCurrent(baseline, component) {
-  return baseline.schemaVersion === 1 && baseline.coreRepository === component.repository && baseline.coreVersion === component.version && baseline.coreCommit === component.commit && baseline.distribution === component.distribution && Array.isArray(baseline.managedPaths) && baseline.managedPaths.length > 0;
+function validateBaselineIdentity(baseline, componentId, component, filename) {
+  if (!Object.keys(baseline).length) return;
+  if (![1, 2].includes(baseline.schemaVersion)) throw new Error(`Unsupported ${filename} schemaVersion`);
+  if (baseline.schemaVersion === 2 && baseline.component !== componentId) throw new Error(`${filename} records a different component`);
+  if (baseline.distribution && baseline.distribution !== component.distribution) throw new Error(`${filename} records a different distribution`);
 }
 
-function deploymentMetadataCurrent(baseline, component) {
-  return baseline.schemaVersion === 1 && baseline.deploymentKitRepository === component.repository && baseline.deploymentKitCommit === component.commit && baseline.distribution === component.distribution && Array.isArray(baseline.managedPaths) && baseline.managedPaths.length > 0;
+function componentMetadataCurrent(baseline, componentId, component) {
+  if (baseline.schemaVersion !== 2 || baseline.component !== componentId) return false;
+  if (baseline.revision !== componentRevision(component) || baseline.distribution !== component.distribution) return false;
+  if (componentId === 'core' && baseline.version !== component.version) return false;
+  return Array.isArray(baseline.managedPaths) && baseline.managedPaths.length > 0;
 }
 
 export function planComponent(packageData, componentId, targetRoot, acceptedRetired = new Set()) {
   const component = packageData.assets.components[componentId];
+  if (!component) throw new Error(`Package does not define component ${componentId}`);
+  componentRevision(component);
   const filename = baselineFile(componentId);
   const baseline = loadOptionalJson(path.join(targetRoot, filename));
-  if (Object.keys(baseline).length && baseline.schemaVersion !== 1) throw new Error(`Unsupported ${filename} schemaVersion`);
-  if (componentId === 'core' && baseline.coreRepository && baseline.coreRepository !== component.repository) throw new Error(`${filename} records a different Core repository`);
-  if (componentId === 'deployment' && baseline.deploymentKitRepository && baseline.deploymentKitRepository !== component.repository) throw new Error(`${filename} records a different Deployment Kit repository`);
-  if (baseline.distribution && baseline.distribution !== component.distribution) throw new Error(`${filename} records a different distribution`);
+  validateBaselineIdentity(baseline, componentId, component, filename);
 
   const entries = componentEntries(packageData, componentId);
   const baseMap = baselineMap(baseline, filename);
@@ -151,30 +162,19 @@ export function planComponent(packageData, componentId, targetRoot, acceptedReti
     rows,
     retired,
     unsafe,
-    metadataCurrent: componentId === 'core' ? coreMetadataCurrent(baseline, component) : deploymentMetadataCurrent(baseline, component)
+    metadataCurrent: componentMetadataCurrent(baseline, componentId, component)
   };
 }
 
 function buildComponentBaseline(plan, consumer, consumerBaseline) {
   const managedPaths = plan.rows.map((row) => ({ source: row.source, path: row.path, sha256: row.desiredHash }));
-  if (plan.componentId === 'core') {
-    return {
-      schemaVersion: 1,
-      consumer,
-      consumerBaseline,
-      coreRepository: plan.component.repository,
-      coreVersion: plan.component.version,
-      coreCommit: plan.component.commit,
-      distribution: plan.component.distribution,
-      managedPaths
-    };
-  }
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
+    component: plan.componentId,
     consumer,
     consumerBaseline,
-    deploymentKitRepository: plan.component.repository,
-    deploymentKitCommit: plan.component.commit,
+    revision: componentRevision(plan.component),
+    ...(plan.component.version ? { version: plan.component.version } : {}),
     distribution: plan.component.distribution,
     managedPaths
   };
@@ -213,15 +213,14 @@ export function applyProfile(packageData, profilePlan, targetRoot, consumer, con
     fs.writeFileSync(path.join(targetRoot, plan.filename), JSON.stringify(baseline, null, 2) + '\n');
   }
   const projectForgeBaseline = {
-    schemaVersion: 1,
+    schemaVersion: 2,
     package: packageData.pkg.name,
     version: packageData.pkg.version,
     profile: profilePlan.profileName,
     consumer,
     consumerBaseline,
     components: Object.fromEntries(profilePlan.plans.map((plan) => [plan.componentId, {
-      repository: plan.component.repository,
-      commit: plan.component.commit,
+      revision: componentRevision(plan.component),
       ...(plan.component.version ? { version: plan.component.version } : {}),
       distribution: plan.component.distribution
     }]))
@@ -233,7 +232,7 @@ export function applyProfile(packageData, profilePlan, targetRoot, consumer, con
 export function checkProfile(packageData, profileName, targetRoot) {
   const plan = planProfile(packageData, profileName, targetRoot);
   const projectForgeBaseline = loadOptionalJson(path.join(targetRoot, 'PROJECT_FORGE_BASELINE.json'));
-  const projectForgeCurrent = projectForgeBaseline.schemaVersion === 1 && projectForgeBaseline.package === packageData.pkg.name && projectForgeBaseline.version === packageData.pkg.version && projectForgeBaseline.profile === profileName;
+  const projectForgeCurrent = projectForgeBaseline.schemaVersion === 2 && projectForgeBaseline.package === packageData.pkg.name && projectForgeBaseline.version === packageData.pkg.version && projectForgeBaseline.profile === profileName;
   const componentClean = plan.plans.every((component) => component.metadataCurrent && component.rows.every((row) => row.state === 'SAME') && component.retired.length === 0);
   return { clean: projectForgeCurrent && componentClean, projectForgeCurrent, plan, projectForgeBaseline };
 }