@mriekki/project-forge 4.4.0 → 4.4.2

package/README.md

@@ -126,6 +126,15 @@ npx @mriekki/project-forge@latest check
 
 Managed updates verify baselines and refuse unsafe drift or conflicts before modifying Project Forge-managed files.
 
+## Maintainer system reference
+
+For cross-repository architecture, ownership, lifecycle, provenance, deployment, support-evidence, and governance questions, start with:
+
+- [`docs/system/PROJECT_FORGE_SYSTEM_REQUIREMENTS.md`](docs/system/PROJECT_FORGE_SYSTEM_REQUIREMENTS.md) — normative cross-repository invariants;
+- [`docs/system/PROJECT_FORGE_SYSTEM_DESIGN.md`](docs/system/PROJECT_FORGE_SYSTEM_DESIGN.md) — explanatory system map and pointers to detailed owning-repository contracts.
+
+The system reference deliberately does not duplicate current component SHAs, package/catalog versions, support status, or implementation-level CLI/schema detail. Resolve mutable facts from the owning repositories and machine-readable Platform/Bootstrap/consumer provenance.
+
 ## Maintainer release process
 
 Project Forge maintainers use a gated release workflow that resolves accepted component commits, verifies the assembled package, creates the package pull request, verifies CI, and stops at the explicit publication gate.

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "4.4.0",
+  "version": "4.4.2",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "45139179c3d10ebd89702ac3aedec231364d8a34",
+      "commit": "d106b1834a8c44bdae0b16e4af5d8dab0711a120",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -23,7 +23,7 @@
     },
     "deployment": {
       "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "eb157c8ae2c638ae1cd08bf27446d430835adc80",
+      "commit": "880a911bc87e38c74ca4b336c9563a6f026ac3b4",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "4.4.0",
+  "version": "4.4.2",
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "45139179c3d10ebd89702ac3aedec231364d8a34",
+      "commit": "d106b1834a8c44bdae0b16e4af5d8dab0711a120",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -22,7 +22,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 +42,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 +187,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",
@@ -328,7 +328,7 @@
     },
     "deployment": {
       "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "eb157c8ae2c638ae1cd08bf27446d430835adc80",
+      "commit": "880a911bc87e38c74ca4b336c9563a6f026ac3b4",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -519,7 +519,7 @@
         {
           "source": "src/project_forge_deployment/sqlite_adapter.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter.py",
-          "sha256": "b6f5fd33b776a1fb02d6b6a00fbab0b95827946e5fee51aafef9446fa084f42b"
+          "sha256": "011615339f739316fb1350a7d4f1385a841744cf09c66da61c10e46f444c059f"
         },
         {
           "source": "src/project_forge_deployment/sqlite_adapter_remote.py",
@@ -529,12 +529,12 @@
         {
           "source": "src/project_forge_deployment/sqlite_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_cli.py",
-          "sha256": "e56fe51fe92110704f709f9b4a3e89f667aa4f827dbf562262b3f89ab7637dfb"
+          "sha256": "abee3a7fbef21f1a02b1511f5d050f90d9ef51afcd6714046c25b786568fb833"
         },
         {
           "source": "src/project_forge_deployment/sqlite_import_recovery.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_import_recovery.py",
-          "sha256": "417096927ae2f36d19df90e26ed88a1f8659a83538155d3538f660a887077f4e"
+          "sha256": "b047494e403963120d8667e189f20ed6310526870b56adb1f433a9b0154c7636"
         },
         {
           "source": "src/project_forge_deployment/ssh.py",

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/assets/generated/deployment/src/project_forge_deployment/sqlite_adapter.py

@@ -252,9 +252,18 @@ def _reservation_from_request(request: dict[str, Any]) -> dict[str, Any]:
     }
 
 
-def plan_sqlite_operation(name: str, action: str, request: dict[str, Any]) -> dict[str, Any]:
+def plan_sqlite_operation(
+    name: str,
+    action: str,
+    request: dict[str, Any],
+    *,
+    production: bool = False,
+) -> dict[str, Any]:
     if action not in {"import", "backup", "migrate", "rollback-check"}:
         raise DeploymentKitError("Unsupported SQLite plan action.")
+    if not isinstance(production, bool):
+        raise DeploymentKitError("SQLite Production classification must be a boolean.")
+    production_classified = production or request["environment"] == "production"
     _require_ready_platform(name)
     inventory = sqlite_inventory(name)
     existing = _find(inventory, request["appSlug"], request["environment"])
@@ -284,7 +293,8 @@ def plan_sqlite_operation(name: str, action: str, request: dict[str, Any]) -> di
             raise DeploymentKitError(f"SQLite {action} requires an existing database.")
     return {
         "targetName": name, "action": action, "ownerRepo": request["ownerRepo"],
-        "environment": request["environment"], "appSlug": request["appSlug"], "image": request["image"],
+        "environment": request["environment"], "productionClassified": production_classified,
+        "appSlug": request["appSlug"], "image": request["image"],
         "databaseFile": spec["databaseFile"], "runAs": spec["runAs"],
         "sourceDatabase": request["sourceDatabase"] if action == "import" else None,
         "firstInstall": bool(request["firstInstall"] if action == "migrate" else False),
@@ -295,7 +305,9 @@ def plan_sqlite_operation(name: str, action: str, request: dict[str, Any]) -> di
 
 
 def authorization_phrase(plan: dict[str, Any]) -> str:
-    production = plan["environment"] == "production"
+    production = plan.get("productionClassified")
+    if not isinstance(production, bool):
+        raise DeploymentKitError("Malformed SQLite operation plan Production classification.")
     mapping = {
         "import": (SQLITE_IMPORT_WRITE_PHRASE, PRODUCTION_SQLITE_IMPORT_WRITE_PHRASE),
         "backup": (SQLITE_BACKUP_WRITE_PHRASE, PRODUCTION_SQLITE_BACKUP_WRITE_PHRASE),
@@ -307,9 +319,11 @@ def authorization_phrase(plan: dict[str, Any]) -> str:
 
 
 def apply_sqlite_operation(plan: dict[str, Any]) -> dict[str, Any]:
-    required = {"targetName", "action", "ownerRepo", "environment", "appSlug", "image", "databaseFile", "runAs", "sourceDatabase", "firstInstall", "stopsManagedRuntime", "createsVerifiedBackup", "inventorySnapshot", "expectedReservationSha256", "spec"}
-    if not isinstance(plan, dict) or set(plan) != required:
+    required = {"targetName", "action", "ownerRepo", "environment", "productionClassified", "appSlug", "image", "databaseFile", "runAs", "sourceDatabase", "firstInstall", "stopsManagedRuntime", "createsVerifiedBackup", "inventorySnapshot", "expectedReservationSha256", "spec"}
+    if not isinstance(plan, dict) or set(plan) != required or not isinstance(plan["productionClassified"], bool):
         raise DeploymentKitError("Malformed SQLite operation plan.")
+    if plan["environment"] == "production" and not plan["productionClassified"]:
+        raise DeploymentKitError("Literal production environment must remain Production-classified.")
     _require_ready_platform(plan["targetName"])
     current = sqlite_inventory(plan["targetName"])
     if _snapshot(current) != plan["inventorySnapshot"]:
@@ -319,6 +333,7 @@ def apply_sqlite_operation(plan: dict[str, Any]) -> dict[str, Any]:
     result = sqlite_inventory(plan["targetName"])
     result["mutated"] = True
     result["operation"] = plan["action"]; result["operationOutput"] = output.strip()
+    result["productionClassified"] = plan["productionClassified"]
     return result
 
 
@@ -332,4 +347,4 @@ def assert_app_spec_matches_persistence(name: str, app_spec: dict[str, Any]) ->
     if existing["runAs"] != app_spec["runAs"]:
         raise DeploymentKitError("Application runAs does not match the prepared SQLite persistence reservation.")
     if app_spec.get("persistence", {}).get("mode") != "directory":
-        raise DeploymentKitError("Prepared SQLite persistence requires directory application persistence.")
+        raise DeploymentKitError("Prepared SQLite persistence requires directory application persistence.")

package/assets/generated/deployment/src/project_forge_deployment/sqlite_cli.py

@@ -38,6 +38,11 @@ def _common(parser: argparse.ArgumentParser) -> None:
     parser.add_argument('name')
     parser.add_argument('--owner-repo', required=True)
     parser.add_argument('--environment', required=True)
+    parser.add_argument(
+        '--production',
+        action='store_true',
+        help="Classify this named environment as Production even when its name is not literally 'production'",
+    )
     parser.add_argument('--app-slug', required=True)
     parser.add_argument('--image', required=True)
     parser.add_argument('--maintenance-env', action='append', default=[], help='Non-secret image maintenance environment value in NAME=value form; repeat as needed')
@@ -68,19 +73,20 @@ def main(argv: list[str]|None=None) -> int:
     args=build_parser().parse_args(argv)
     try:
         if args.command=='inventory': _print(sqlite_inventory(args.name),as_json=args.json); return 0
+        production_classified = args.production or args.environment == 'production'
         request=normalize_sqlite_request(owner_repo=args.owner_repo,environment=args.environment,app_slug=args.app_slug,image=args.image,
             maintenance_environment=_parse_env(args.maintenance_env),run_as=getattr(args,'run_as',None),database_file=getattr(args,'database_file',None),
             source_database=getattr(args,'source_database',None),first_install=getattr(args,'first_install',False))
         if args.command=='recover-import':
-            plan=plan_sqlite_import_recovery(args.name,request)
+            plan=plan_sqlite_import_recovery(args.name,request,production=production_classified)
             _print({k:v for k,v in plan.items() if k!='request'},as_json=False)
             phrase=recovery_authorization_phrase(plan)
             _confirm(args,phrase,f"recover SQLite import for {plan['appSlug']} ({plan['environment']}) on target {args.name}")
             _print(apply_sqlite_import_recovery(plan),as_json=args.json); return 0
-        plan=plan_sqlite_operation(args.name,args.command,request)
+        plan=plan_sqlite_operation(args.name,args.command,request,production=production_classified)
         _print({k:v for k,v in plan.items() if k!='spec'},as_json=False)
         phrase=authorization_phrase(plan)
         _confirm(args,phrase,f"run SQLite {args.command} for {plan['appSlug']} ({plan['environment']}) on target {args.name}")
         _print(apply_sqlite_operation(plan),as_json=args.json); return 0
     except DeploymentKitError as error:
-        print(f"ERROR: {error}",file=sys.stderr); return 2
+        print(f"ERROR: {error}",file=sys.stderr); return 2

package/assets/generated/deployment/src/project_forge_deployment/sqlite_import_recovery.py

@@ -356,13 +356,22 @@ def _snapshot(inspection: dict[str, Any]) -> str:
     return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")).hexdigest()
 
 
-def plan_sqlite_import_recovery(name: str, request: dict[str, Any]) -> dict[str, Any]:
+def plan_sqlite_import_recovery(
+    name: str,
+    request: dict[str, Any],
+    *,
+    production: bool = False,
+) -> dict[str, Any]:
+    if not isinstance(production, bool):
+        raise DeploymentKitError("SQLite Production classification must be a boolean.")
+    production_classified = production or request["environment"] == "production"
     inspection = inspect_sqlite_import_recovery(name, request)
     return {
         "targetName": name,
         "action": "recover-import",
         "ownerRepo": request["ownerRepo"],
         "environment": request["environment"],
+        "productionClassified": production_classified,
         "appSlug": request["appSlug"],
         "image": request["image"],
         "runAs": request["runAs"],
@@ -381,22 +390,32 @@ def plan_sqlite_import_recovery(name: str, request: dict[str, Any]) -> dict[str,
 
 
 def authorization_phrase(plan: dict[str, Any]) -> str:
+    production = plan.get("productionClassified")
+    if not isinstance(production, bool):
+        raise DeploymentKitError("Malformed SQLite import recovery Production classification.")
     return (
         PRODUCTION_SQLITE_IMPORT_RECOVERY_WRITE_PHRASE
-        if plan["environment"] == "production"
+        if production
         else SQLITE_IMPORT_RECOVERY_WRITE_PHRASE
     )
 
 
 def apply_sqlite_import_recovery(plan: dict[str, Any]) -> dict[str, Any]:
     required = {
-        "targetName", "action", "ownerRepo", "environment", "appSlug", "image", "runAs",
+        "targetName", "action", "ownerRepo", "environment", "productionClassified", "appSlug", "image", "runAs",
         "databaseFile", "sourceDatabase", "databaseSha256", "sourceSha256", "databaseBytes",
         "stateSnapshot", "overwritesDatabase", "deletesPersistentData", "createsReservation",
         "reverifiesDatabase", "request",
     }
-    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "recover-import":
+    if (
+        not isinstance(plan, dict)
+        or set(plan) != required
+        or plan["action"] != "recover-import"
+        or not isinstance(plan["productionClassified"], bool)
+    ):
         raise DeploymentKitError("Malformed SQLite import recovery plan.")
+    if plan["environment"] == "production" and not plan["productionClassified"]:
+        raise DeploymentKitError("Literal production environment must remain Production-classified.")
     current = inspect_sqlite_import_recovery(plan["targetName"], plan["request"])
     if _snapshot(current) != plan["stateSnapshot"]:
         raise DeploymentKitError(
@@ -434,4 +453,5 @@ def apply_sqlite_import_recovery(plan: dict[str, Any]) -> dict[str, Any]:
     inventory["mutated"] = True
     inventory["operation"] = "recover-import"
     inventory["operationOutput"] = output.strip()
+    inventory["productionClassified"] = plan["productionClassified"]
     return inventory

package/package.json

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