@mriekki/project-forge 4.12.0 → 4.13.0

package/README.md

@@ -113,6 +113,8 @@ Generated Projects receive an exact approved package during deterministic genera
 
 That Project workflow resolves the supported exact package version and preserves the managed-baseline, drift, review, and delivery guardrails. Do not use a floating `@latest` package update as the normal Builder path: npm publication can intentionally occur before the stable public contract is advanced to the new version.
 
+Package-managed updates follow the **Exact Managed Set** invariant: after a successful update, every path still managed by the selected package/profile has the package-defined content, and every previously managed path that the new package retires has either been removed or explicitly transferred out of Project Forge ownership. Unmanaged consumer files are not directory-mirrored or pruned. See [`docs/system/PROJECT_FORGE_EXACT_MANAGED_SET.md`](docs/system/PROJECT_FORGE_EXACT_MANAGED_SET.md).
+
 The package CLI remains available for exact-version troubleshooting and maintainer verification. Use the exact version recorded by the Project or selected by the Project Forge workflow rather than a floating tag.
 
 ## Maintainer system reference

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,7 +13,7 @@
   },
   "components": {
     "core": {
-      "revision": "ed6a52538a03cb92850cafe0cb8404c39b8e5b89",
+      "revision": "27f6824d1a53daa7e0c51bf286cce6767ddca3f7",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "8df115fe5c27fcf6647d7e87258166616e8e2e53",
+      "revision": "1119331414ec53e0c48b864403fabfef7998df60",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/core/distribution.json

@@ -5,6 +5,7 @@
   "mappings": [
     {"source":"core/agents/reviewer.agent.md","destination":".github/agents/reviewer.agent.md"},
     {"source":"core/instructions/project-forge-workflow.instructions.md","destination":".github/instructions/project-forge-workflow.instructions.md"},
+    {"source":"core/instructions/project-forge-local-development.instructions.md","destination":".github/instructions/project-forge-local-development.instructions.md"},
     {"source":"core/instructions/project-forge-docs.instructions.md","destination":".github/instructions/project-forge-docs.instructions.md"},
     {"source":"core/skills/define-feature/SKILL.md","destination":".github/skills/define-feature/SKILL.md"},
     {"source":"core/skills/grill-me/SKILL.md","destination":".github/skills/grill-me/SKILL.md"},
@@ -48,6 +49,7 @@
     {"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/process/LOCAL_DEVELOPMENT_COMMANDS.md","destination":"docs/process/LOCAL_DEVELOPMENT_COMMANDS.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/deployment/distribution.json

@@ -42,6 +42,7 @@
     {"source": "src/project_forge_deployment/profiles.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profiles.py"},
     {"source": "src/project_forge_deployment/project_topology.py", "destination": "tools/project-forge-deployment/project_forge_deployment/project_topology.py"},
     {"source": "src/project_forge_deployment/proof_receipt.py", "destination": "tools/project-forge-deployment/project_forge_deployment/proof_receipt.py"},
+    {"source": "src/project_forge_deployment/recovery_scope.py", "destination": "tools/project-forge-deployment/project_forge_deployment/recovery_scope.py"},
     {"source": "src/project_forge_deployment/registry_access.py", "destination": "tools/project-forge-deployment/project_forge_deployment/registry_access.py"},
     {"source": "src/project_forge_deployment/registry_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/registry_cli.py"},
     {"source": "src/project_forge_deployment/route_registry.py", "destination": "tools/project-forge-deployment/project_forge_deployment/route_registry.py"},
@@ -62,6 +63,7 @@
     {"source": "docs/WORKSPACE_INSTANCES.md", "destination": "docs/project-forge/WORKSPACE_INSTANCES.md"},
     {"source": "docs/ENVIRONMENT_PROOF.md", "destination": "docs/project-forge/ENVIRONMENT_PROOF.md"},
     {"source": "docs/PROJECT_TOPOLOGY_BINDING.md", "destination": "docs/project-forge/PROJECT_TOPOLOGY_BINDING.md"},
+    {"source": "docs/RECOVERY_READINESS.md", "destination": "docs/project-forge/RECOVERY_READINESS.md"},
     {"source": "docs/images/developer-environment-journey.svg", "destination": "docs/project-forge/images/developer-environment-journey.svg"},
     {"source": "docs/images/personal-environment-architecture.svg", "destination": "docs/project-forge/images/personal-environment-architecture.svg"},
     {"source": "docs/images/project-environment-model.svg", "destination": "docs/project-forge/images/project-environment-model.svg"}

package/assets/generated/ASSEMBLY.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "components": {
     "core": {
-      "revision": "ed6a52538a03cb92850cafe0cb8404c39b8e5b89",
+      "revision": "27f6824d1a53daa7e0c51bf286cce6767ddca3f7",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -23,6 +23,11 @@
           "destination": ".github/instructions/project-forge-workflow.instructions.md",
           "sha256": "dd440f677c9ed476bb8b7486500d8acbe2f796272582baadd4d6a60c3d1e662c"
         },
+        {
+          "source": "core/instructions/project-forge-local-development.instructions.md",
+          "destination": ".github/instructions/project-forge-local-development.instructions.md",
+          "sha256": "e7f884f123877b21913af111cde42fc0ff0ac82abe6fd18b8f4584d749fb6c3a"
+        },
         {
           "source": "core/instructions/project-forge-docs.instructions.md",
           "destination": ".github/instructions/project-forge-docs.instructions.md",
@@ -56,12 +61,12 @@
         {
           "source": "core/skills/build/SKILL.md",
           "destination": ".github/skills/build/SKILL.md",
-          "sha256": "0659ad88cac5ca652eedba648d10a39ca1d51d65db638ce41b392067a3fd6128"
+          "sha256": "e7ba7663a99603f1212930045bec420c71774e56cad963e38867242605afdad4"
         },
         {
           "source": "core/skills/run/SKILL.md",
           "destination": ".github/skills/run/SKILL.md",
-          "sha256": "6bdf23f46609d1b85147347d313d7c4bf13bd8bfc91d4b782fc7a311189ffbe3"
+          "sha256": "3dfc25cff7b03eafe0b8d64cc2102584c7b90793f434313f62c9e61c1b587c9e"
         },
         {
           "source": "core/skills/export-requirements/SKILL.md",
@@ -238,6 +243,11 @@
           "destination": "docs/process/APPLICATION_VERSIONING.md",
           "sha256": "846abd1085501bebf3ffd8025f875dcf2bfb3f57e67110e684c605ae11c3246b"
         },
+        {
+          "source": "core/process/LOCAL_DEVELOPMENT_COMMANDS.md",
+          "destination": "docs/process/LOCAL_DEVELOPMENT_COMMANDS.md",
+          "sha256": "44a62a68cbf211658d0e928f595b357fab3993eebbe5228ffeab9336b79e7ba6"
+        },
         {
           "source": "core/templates/PULL_REQUEST_TEMPLATE.md",
           "destination": ".github/PULL_REQUEST_TEMPLATE.md",
@@ -351,7 +361,7 @@
       ]
     },
     "deployment": {
-      "revision": "8df115fe5c27fcf6647d7e87258166616e8e2e53",
+      "revision": "1119331414ec53e0c48b864403fabfef7998df60",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -549,6 +559,11 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/proof_receipt.py",
           "sha256": "9b4bbb559747fc4ee3ba984a050fc6425e532527ae82f9897c73e04d8d0291b6"
         },
+        {
+          "source": "src/project_forge_deployment/recovery_scope.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/recovery_scope.py",
+          "sha256": "1773369f26dea95795eb971a8433699897db74d6c38223c0d93c8626c3b9f2aa"
+        },
         {
           "source": "src/project_forge_deployment/registry_access.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/registry_access.py",
@@ -577,17 +592,17 @@
         {
           "source": "src/project_forge_deployment/sqlite_adapter.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter.py",
-          "sha256": "011615339f739316fb1350a7d4f1385a841744cf09c66da61c10e46f444c059f"
+          "sha256": "ab0fe2a1009ac1883ee7c9344c84240051648ccd1f05df9166cd81f6a216f893"
         },
         {
           "source": "src/project_forge_deployment/sqlite_adapter_remote.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter_remote.py",
-          "sha256": "a21006aec6bfa235535fdde4441cf658bb1cec32bd27a0b3840babe77440c2fb"
+          "sha256": "6c7ba2c49f8ae97a28927f694df23b7f18de1247aac4bc4dce858859fb2199ed"
         },
         {
           "source": "src/project_forge_deployment/sqlite_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_cli.py",
-          "sha256": "abee3a7fbef21f1a02b1511f5d050f90d9ef51afcd6714046c25b786568fb833"
+          "sha256": "37132cc141afe9196a96fd91db55597998886d037b2baded62526c08df148f5d"
         },
         {
           "source": "src/project_forge_deployment/sqlite_import_recovery.py",
@@ -649,6 +664,11 @@
           "destination": "docs/project-forge/PROJECT_TOPOLOGY_BINDING.md",
           "sha256": "50988ac1d797494bcb2d5dd6cece04f6313fb30179ca3132191dea75bcd759cd"
         },
+        {
+          "source": "docs/RECOVERY_READINESS.md",
+          "destination": "docs/project-forge/RECOVERY_READINESS.md",
+          "sha256": "ae94a858c9431ad1f432cb75e76b532d83f69c8ca163707ac12d9ea11c60edc1"
+        },
         {
           "source": "docs/images/developer-environment-journey.svg",
           "destination": "docs/project-forge/images/developer-environment-journey.svg",

package/assets/generated/core/core/instructions/project-forge-local-development.instructions.md

@@ -0,0 +1,28 @@
+---
+applyTo: "**"
+---
+
+# Project Forge Local Development Contract
+
+Keep Core stack-neutral and Projects operationally deterministic. Follow `docs/process/LOCAL_DEVELOPMENT_COMMANDS.md` when it exists.
+
+When an Engineering Enabler or equivalent foundational work item first establishes executable application topology, establish unambiguous repository-owned build and run commands for the normal developer path. Do not require a particular wrapper language or invent placeholder commands before executable topology exists.
+
+For Feature Brief and Engineering Enabler implementation/validation, default application execution and persistence operations to the established Project-owned local developer runtime and its associated persistence unless the developer explicitly selects a supported alternative. When the Project defines a local container/database pair as that topology, do not silently substitute a native process or separate checkout database.
+
+If the established default runtime/persistence is absent, stopped, stale, or blocked by initialization/schema prerequisites, route through `/setup local` or the repository-owned repair workflow. Do not bypass it by selecting another runtime/database. Preserve `/run`'s no-implicit-setup/no-automatic-migration boundary.
+
+When a work item materially changes executable topology, assess and maintain the affected Project-owned engineering interfaces in the same accepted change:
+
+```text
+BUILD CONTRACT IMPACT
+RUN CONTRACT IMPACT
+SETUP CONTRACT IMPACT
+CI CONTRACT IMPACT
+```
+
+Examples include build-system changes, native/container changes, component composition, persistence ownership/location, launch profiles/ports, transport/authentication requirements, readiness checks, and stop/cleanup mechanics.
+
+Prefer the same underlying repository-owned build entry point in CI where practical. Preserve repository-required isolated/disposable test runtimes and databases; never redirect automated tests into mutable developer data merely to reuse the normal developer runtime.
+
+A failing or stale established build/run command is a Project contract problem. Do not silently bypass it with ecosystem-native inference. Framework-native discovery remains a fallback only while no Project-owned command contract exists yet or when the developer explicitly selects a supported alternative.

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

@@ -0,0 +1,103 @@
+# Local Development Command Contract
+
+## Principle
+
+Project Forge Core is generic; each executable Project should become deterministic.
+
+Bootstrap and early discovery do not need to know framework-specific build/run mechanics. Once an Engineering Enabler or equivalent foundational work item establishes executable application topology, the Project should expose unambiguous repository-owned commands for normal developer build and run behavior.
+
+This contract does not require literal `build.ps1` or `run.ps1` files and does not introduce a `PROJECT_COMMANDS.json` registry. A repository-owned command may be a wrapper script, package/task script, Compose command, build-tool target, Make target, or another deterministic command already owned by the Project.
+
+## Establishment
+
+When the first foundational Engineering Enabler makes the application executable, establish the normal local developer contract as applicable:
+
+```text
+Build ........ authoritative Project-owned build command
+Run .......... authoritative Project-owned developer runtime command
+Persistence .. runtime-associated developer persistence, when applicable
+Stop ......... how the normal developer runtime is stopped
+Readiness .... what proves the selected runtime is actually ready
+Transport .... required local HTTP/HTTPS/authentication properties when applicable
+```
+
+If application scaffolding or runtime is intentionally deferred, do not create placeholder commands merely to satisfy this contract. Ecosystem-native inference may remain a temporary fallback until executable topology exists.
+
+## Default runtime and persistence
+
+For Feature Brief and Engineering Enabler implementation/validation, use the established Project-owned local developer runtime and its associated persistence by default unless the developer explicitly selects a supported alternative.
+
+When the Project defines a local container and associated database as its developer topology, that container/database pair is the default. Do not silently substitute a native process or separate checkout database merely because an ecosystem-native command is easier to invoke.
+
+If the default runtime is absent, stopped, stale, or blocked by missing/pending schema prerequisites, route through `/setup local` or the repository-owned repair workflow. Do not bypass the problem by selecting another runtime/database.
+
+An explicit developer selection may authorize a supported alternative within the relevant operation's existing boundaries. Once selected, inspect and operate only against that runtime and its persistence.
+
+Automated tests remain separate: preserve isolated/disposable test databases or runtimes required by the repository's test contract. Never redirect tests into mutable developer data merely to reuse the developer run contract.
+
+## Build command lifecycle
+
+`/build` prefers the established Project-owned build command. Once that command exists, it is authoritative for the normal build target; a failing or stale wrapper is a Project contract problem, not permission to silently bypass it with framework-native fallback.
+
+Where practical, CI should invoke the same underlying repository-owned build entry point so local and CI build semantics do not drift.
+
+A work item that materially changes build topology should assess and update the build contract in the same accepted change. Examples include:
+
+- changing build systems or package managers;
+- splitting/combining application components;
+- changing generated artifacts or build outputs;
+- moving from native build orchestration to containerized build orchestration;
+- changing required build-time configuration or dependency preparation.
+
+## Run command lifecycle
+
+`/run` prefers the established Project-owned runtime and associated persistence. A work item that materially changes local runtime topology should assess and update the run contract in the same accepted change. Examples include:
+
+- native/container topology changes;
+- frontend/backend composition changes;
+- persistence engine/path/volume changes;
+- launch-profile or port changes;
+- HTTP/HTTPS or authentication transport changes;
+- required initialization/migration/readiness behavior;
+- stop/cleanup mechanics.
+
+The run command must not hide setup or destructive repair. `/run` may perform read-only prerequisite checks, but normal installation, forward initialization/migration, container convergence, or repair remain owned by `/setup` or repository-specific setup tooling.
+
+## Readiness semantics
+
+Process startup is not application readiness.
+
+Keep these dimensions distinct:
+
+```text
+Process startup
+Artifact/version identity
+Persistence/schema readiness
+Transport readiness
+Functional checks actually performed
+```
+
+A successful `/version` call, open database connection, or connection-only health endpoint does not prove schema compatibility, authentication usability, OAuth readiness, or another user workflow unless that condition is independently verified.
+
+When safe non-mutating verification is unavailable, report the gap instead of inventing confidence.
+
+## Command resolution fallback
+
+Core remains stack-neutral. `/build` and `/run` may still infer an unambiguous ecosystem-native command when no Project-owned command exists yet. That is a fallback for early/incomplete Projects, not the preferred mature state.
+
+Once a Project-owned command exists, do not silently fall through to a different native command because the authoritative command fails. Fix or explicitly change the Project contract through the relevant accepted work item.
+
+## Work-item maintenance rule
+
+For Feature Brief and Engineering Enabler work that materially changes executable application topology, the implementation/review should assess these impacts before delivery:
+
+```text
+BUILD CONTRACT IMPACT
+RUN CONTRACT IMPACT
+SETUP CONTRACT IMPACT
+CI CONTRACT IMPACT
+```
+
+Update affected Project-owned commands and documentation in the same work item rather than leaving them for rediscovery in a later session.
+
+This is an engineering-interface maintenance rule, not a requirement that every work item touch build/run files.

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

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 # Build
 
-`/build` is a thin local helper. It hides framework-specific command details while preserving the repository as the authority for how the project builds.
+`/build` is a thin local helper. Core stays stack-neutral; the Project becomes deterministic by exposing a repository-owned build command once executable application topology exists. Follow `docs/process/LOCAL_DEVELOPMENT_COMMANDS.md` when present.
 
 ## Contract
 
@@ -16,12 +16,17 @@ Invoking `/build` authorizes one bounded local build attempt for the requested t
 
 Resolve the build command from current repository evidence in this order:
 
-1. an explicit repository-owned build wrapper or documented build command;
-2. an explicit package/task script whose purpose is build;
-3. an unambiguous ecosystem-native build entry point already present in the repository.
+1. an explicit developer-selected supported build target, when one was supplied;
+2. an explicit repository-owned build wrapper or documented command;
+3. an explicit package/task script whose purpose is build;
+4. an unambiguous ecosystem-native build entry point already present in the repository, but only when the Project has not yet established a repository-owned build contract.
 
 Do not invent a command because a framework is recognizable. If multiple materially different build targets exist and no default is documented, require a target such as `/build web`, `/build api`, or `/build all`.
 
+Once an executable Project has an established repository-owned build command, treat that command as authoritative. If it is missing, stale, or fails because the Project topology changed, report the contract problem; do not silently bypass it with a framework-native fallback. The work item that materially changes build topology should maintain the Project-owned build command in the same accepted change.
+
+During an intentionally deferred or first-scaffold phase, ecosystem-native inference remains a fallback. Repeated inference is not the preferred mature Project state.
+
 ## Preconditions
 
 Before execution:
@@ -40,7 +45,7 @@ If dependencies or workstation tools are missing, recommend `/setup` rather than
 Run the selected build visibly and report:
 
 - target;
-- resolved repository-owned command identity;
+- resolved repository-owned command identity, or clearly labeled inference fallback when no Project-owned command exists yet;
 - success/failure and exit code when available;
 - produced artifact/output locations when the build contract makes them explicit;
 - effective application release/build identity when the build exposes it;

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

@@ -8,47 +8,72 @@ 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.
+`/run` is the normal convenience entry point for starting the project locally. Core stays stack-neutral; the Project becomes deterministic by exposing a repository-owned local runtime command and runtime/persistence pairing once executable application topology exists. Follow `docs/process/LOCAL_DEVELOPMENT_COMMANDS.md` when present.
 
 ## 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.
+Invoking `/run` authorizes one bounded local start attempt for the requested target. It does not authorize setup, source edits, migrations, database reset/replacement, 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:
+Resolve the local runtime 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.
+1. an explicit developer-selected supported runtime/target, when one was supplied;
+2. the established Project-owned default local runtime and its associated persistence, including a project-owned local container/database when the repository defines that as the developer topology;
+3. an explicit repository-owned run/dev wrapper or documented command for that selected runtime;
+4. an explicit package/task script whose purpose is local run/dev;
+5. an unambiguous ecosystem-native local entry point already present in the repository, but only when the Project has not yet established a repository-owned runtime contract.
 
 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`.
 
+For normal Feature Brief and Engineering Enabler development/validation, default to the established Project-owned local runtime and associated persistence unless the developer explicitly selects an alternative. Do not silently start a native process or use a separate checkout database merely because an ecosystem-native command is convenient.
+
+Once a repository-owned runtime command exists, treat it as authoritative for that runtime. If it is stale or fails because topology changed, report the contract problem; do not silently bypass it with another runtime/database.
+
 ## Preconditions
 
 Before starting:
 
 - identify repository root and current Git state;
 - inspect `PROJECT_BOOTSTRAP.json` and scaffold/readiness evidence when present;
+- resolve the exact selected runtime and, when applicable, the persistence instance it owns or uses;
 - verify the selected runtime entry point exists;
-- inspect any documented local ports/health endpoints;
+- inspect documented local ports, health endpoints, launch profiles, and transport/authentication requirements;
 - 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.
 
+### Persistence and schema readiness
+
+When the selected runtime requires persistence, inspect repository-owned non-mutating readiness evidence for the **exact selected persistence instance** before claiming functional readiness. This may include installed Project Forge/Deployment Kit status primitives, migration status commands, repository health/doctor commands, or other documented read-only checks.
+
+- If initialization or required schema is known to be missing/stale, do not automatically migrate, reset, delete, replace, or switch databases. Report `PERSISTENCE BLOCKED` and route to `/setup local` or the repository-owned repair workflow.
+- If the repository does not expose a safe way to establish schema compatibility, report `PERSISTENCE UNVERIFIED`. Do not turn a successful connection, process start, `/version`, or connection-only health check into an application-readiness claim.
+- If the application has no persistence requirement for the selected runtime, report persistence as `N/A`; do not invent a database gate.
+
+A stopped, absent, stale, or migration-pending Project-owned default container/database is a prerequisite problem, not permission to select a different runtime. An explicit developer selection may authorize a supported alternative within the existing `/run` boundary; inspect only that selected runtime and persistence.
+
+### Transport/authentication readiness
+
+Resolve documented transport prerequisites before choosing a launch profile. If normal authentication development requires HTTPS, secure cookies, or another repository-declared transport property, use the supported Project-owned profile/runtime when available or report the unresolved prerequisite. Do not disable secure-cookie policy, invent TLS/provider settings, or weaken authentication configuration to make `/run` succeed.
+
 ## Execution
 
-Start the process in an observable developer-controlled terminal/process surface. Do not hide a long-running application in an unexplained background process.
+Start the selected process/runtime in an observable developer-controlled terminal/process surface. Do not hide a long-running application in an unexplained background process.
 
-Report:
+Report these evidence dimensions separately:
 
-- target;
+- target and selected runtime identity;
 - 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;
+- persistence readiness: `READY`, `BLOCKED`, `UNVERIFIED`, or `N/A`;
+- local URL/port and transport evidence only when repository/runtime evidence establishes it;
+- functional checks actually performed and their result;
 - how to stop the process.
 
+Do not equate startup, artifact identity, `/version`, or connection-only health with successful user workflows. Do not claim login, OAuth callback/provider readiness, or another functional path was verified unless that exact path was exercised successfully.
+
 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.
@@ -57,7 +82,7 @@ When the project implements `docs/process/APPLICATION_VERSIONING.md`, prefer run
 
 `/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.
+Record selected runtime/persistence identity (without secrets), startup command identity, target, timestamps, process/startup result, persistence readiness, functional checks actually performed, 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
 
@@ -66,10 +91,11 @@ Record startup command identity, target, timestamps, startup/health result, obse
 It must not:
 
 - mutate remote environments;
+- perform setup or migration writes implicitly;
 - 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.
+A successful `/run` proves only the evidence dimensions actually observed for the selected local runtime in that session.

package/assets/generated/deployment/docs/RECOVERY_READINESS.md

@@ -0,0 +1,66 @@
+# Recovery Readiness Contract V1
+
+Project Forge distinguishes a verified database backup from verified application recovery. A successful SQLite backup proves only the database artifact created by the application's SQLite maintenance contract; it does not prove that every dependency required to recover authentication or the full application is available or usable.
+
+## Recovery states
+
+Reusable evidence must keep these concepts separate:
+
+1. `databaseBackupVerified` — the SQLite database backup operation completed successfully.
+2. `verifiedBackupScope` — currently `database` for SQLite backup evidence.
+3. `recoveryScopeDeclared` — the consumer supplied a strict, non-secret recovery declaration.
+4. `unresolvedRequiredDependencies` — required non-database dependencies that still need recovery-time verification.
+5. `authenticationPolicyVerified` — the selected authentication recovery policy has been dynamically verified after restore.
+6. `applicationRecoveryReady` — all required recovery dependencies and the selected policy have been verified for the restored application.
+
+Current SQLite backup/import/migration commands never set `applicationRecoveryReady` to true. Deployment Kit does not yet provide a general restore engine.
+
+## Recovery manifest
+
+`sqlite backup` and existing-database `sqlite migrate` may receive `--recovery-manifest <path>` pointing to UTF-8 JSON with exactly this schema:
+
+```json
+{
+  "schemaVersion": 1,
+  "authenticationPolicy": "invalidate-authentication",
+  "dependencies": [
+    {
+      "id": "data-protection-key-ring",
+      "type": "cryptographic-key-ring",
+      "required": true
+    }
+  ]
+}
+```
+
+`authenticationPolicy` may be `preserve-authentication`, `invalidate-authentication`, or `null`. Dependency IDs/types are non-secret identifiers only. Unknown fields fail closed. Do not put paths, keys, credentials, cookies, tokens, passwords, action links, provider secrets, or secret values in the manifest.
+
+The normalized manifest is fingerprinted deterministically and the privacy-safe declaration/readiness summary is included in SQLite evidence. Secret contents are neither archived nor printed by this contract. First-install migration, import, interrupted-import recovery, and rollback checking do not accept a recovery manifest in V1.
+
+## Authentication recovery policies
+
+`preserve-authentication` means a future recovery workflow must prove that required cryptographic/protector dependencies remain usable and that retaining historical authentication state is acceptable.
+
+`invalidate-authentication` means a future recovery workflow must prove that sessions and action links from historical state cannot authenticate or mutate accounts after recovery. Merely replacing a key ring is not sufficient evidence because password hashes, security stamps, sessions, token expiry/consumption, and similar state may also exist in the restored database.
+
+Neither policy is considered verified by a database backup alone.
+
+## Pre-traffic invariant
+
+A future restore operation must fail closed and keep the restored application unavailable to normal traffic until all required recovery dependencies and the selected authentication policy have been verified. Restore completion and database integrity must never be treated as equivalent to application recovery readiness.
+
+## Requirements
+
+- **PF-REC-001** — Database backup verification must never imply whole-application recovery readiness.
+- **PF-REC-002** — Consumers may declare non-database recovery dependencies without exposing secret values.
+- **PF-REC-003** — Required dependencies must be verified before application recovery readiness can pass.
+- **PF-REC-004** — Authentication-bearing consumers must select an explicit post-restore authentication policy when they want application recovery readiness.
+- **PF-REC-005** — Historical restore must remain unavailable to normal traffic until that policy is verified.
+- **PF-REC-006** — Incomplete or failed recovery evidence fails closed.
+- **PF-REC-007** — Existing SQLite-only consumers retain current database backup behavior and database-only success semantics.
+- **PF-REC-008** — Read-only planning/readiness inspection performs no restore, key manipulation, revocation, rotation, or other destructive action.
+- **PF-REC-009** — Dynamic recovery validation uses disposable fixtures and never logs secret material.
+
+## Non-scope
+
+This contract does not implement generic secret archival, provider-specific secret storage, key transport, key rotation, session/token mutation, or a general database/application restore workflow. Those require separate requirements, plan approval, implementation review, and release/adoption gates.

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

@@ -0,0 +1,116 @@
+"""Reusable recovery-scope declarations and non-secret readiness evidence."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any
+
+from .errors import DeploymentKitError
+
+RECOVERY_SCHEMA_VERSION = 1
+AUTHENTICATION_POLICIES = {"preserve-authentication", "invalidate-authentication"}
+_ID_RE = re.compile(r"^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$")
+_ALLOWED_TOP = {"schemaVersion", "authenticationPolicy", "dependencies"}
+_ALLOWED_DEPENDENCY = {"id", "type", "required"}
+
+
+def _identifier(value: Any, field: str) -> str:
+    if not isinstance(value, str) or _ID_RE.fullmatch(value) is None:
+        raise DeploymentKitError(f"{field} must use lowercase letters, digits, dots, underscores, and internal hyphens.")
+    return value
+
+
+def normalize_recovery_scope(value: dict[str, Any] | None) -> dict[str, Any]:
+    """Normalize a strict, non-secret recovery declaration.
+
+    The declaration deliberately has no free-form values, paths, credentials, or
+    provider configuration. It describes recovery dependencies without storing
+    their contents or teaching generic persistence tooling how to archive them.
+    """
+    if value is None:
+        return {
+            "schemaVersion": RECOVERY_SCHEMA_VERSION,
+            "declared": False,
+            "authenticationPolicy": None,
+            "dependencies": [],
+            "manifestSha256": None,
+        }
+    if not isinstance(value, dict) or set(value) != _ALLOWED_TOP:
+        raise DeploymentKitError(
+            "Recovery manifest must contain exactly schemaVersion, authenticationPolicy, and dependencies."
+        )
+    if value["schemaVersion"] != RECOVERY_SCHEMA_VERSION:
+        raise DeploymentKitError(f"Recovery manifest schemaVersion must be {RECOVERY_SCHEMA_VERSION}.")
+    policy = value["authenticationPolicy"]
+    if policy is not None and policy not in AUTHENTICATION_POLICIES:
+        raise DeploymentKitError(
+            "authenticationPolicy must be preserve-authentication, invalidate-authentication, or null."
+        )
+    dependencies = value["dependencies"]
+    if not isinstance(dependencies, list):
+        raise DeploymentKitError("Recovery manifest dependencies must be an array.")
+    normalized: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for dependency in dependencies:
+        if not isinstance(dependency, dict) or set(dependency) != _ALLOWED_DEPENDENCY:
+            raise DeploymentKitError("Each recovery dependency must contain exactly id, type, and required.")
+        dependency_id = _identifier(dependency["id"], "Recovery dependency id")
+        dependency_type = _identifier(dependency["type"], "Recovery dependency type")
+        required = dependency["required"]
+        if not isinstance(required, bool):
+            raise DeploymentKitError("Recovery dependency required must be a boolean.")
+        if dependency_id in seen:
+            raise DeploymentKitError(f"Duplicate recovery dependency id: {dependency_id}")
+        seen.add(dependency_id)
+        normalized.append({"id": dependency_id, "type": dependency_type, "required": required})
+    normalized.sort(key=lambda item: item["id"])
+    canonical = {
+        "schemaVersion": RECOVERY_SCHEMA_VERSION,
+        "authenticationPolicy": policy,
+        "dependencies": normalized,
+    }
+    fingerprint = hashlib.sha256(
+        json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+    return {
+        **canonical,
+        "declared": True,
+        "manifestSha256": fingerprint,
+    }
+
+
+def public_recovery_scope(scope: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "schemaVersion": scope["schemaVersion"],
+        "declared": scope["declared"],
+        "authenticationPolicy": scope["authenticationPolicy"],
+        "dependencies": [dict(item) for item in scope["dependencies"]],
+        "manifestSha256": scope["manifestSha256"],
+    }
+
+
+def recovery_readiness(scope: dict[str, Any], *, database_backup_verified: bool) -> dict[str, Any]:
+    unresolved = [item["id"] for item in scope["dependencies"] if item["required"]]
+    return {
+        "schemaVersion": RECOVERY_SCHEMA_VERSION,
+        "databaseBackupVerified": bool(database_backup_verified),
+        "verifiedBackupScope": "database" if database_backup_verified else None,
+        "recoveryScopeDeclared": scope["declared"],
+        "authenticationPolicy": scope["authenticationPolicy"],
+        "authenticationPolicyVerified": False if scope["authenticationPolicy"] is not None else None,
+        "unresolvedRequiredDependencies": unresolved,
+        "manifestSha256": scope["manifestSha256"],
+        "applicationRecoveryReady": False,
+        "readinessReason": "restore-policy-not-verified" if scope["declared"] else "recovery-scope-not-declared",
+    }
+
+
+def recovery_evidence(scope: dict[str, Any], *, database_backup_verified: bool) -> dict[str, Any]:
+    """Return the privacy-safe evidence payload persisted with a SQLite operation."""
+    readiness = recovery_readiness(scope, database_backup_verified=database_backup_verified)
+    return {
+        **readiness,
+        "dependencies": [dict(item) for item in scope["dependencies"]],
+    }

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

@@ -14,6 +14,7 @@ from .app_runtime import APP_ROOT
 from .box_platform import platform_status
 from .errors import DeploymentKitError
 from .profiles import load_profile
+from .recovery_scope import normalize_recovery_scope, public_recovery_scope, recovery_evidence, recovery_readiness
 from .sqlite_adapter_remote import REMOTE_SCRIPT
 from .ssh import ssh_args, verify_access
 
@@ -111,6 +112,7 @@ def normalize_sqlite_request(
     maintenance_environment: dict[str, str] | Iterable[tuple[str, str]],
     run_as: str | None = None, database_file: str | None = None,
     source_database: str | None = None, first_install: bool = False,
+    recovery_scope: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     request = {
         "ownerRepo": _owner_repo(owner_repo),
@@ -122,6 +124,7 @@ def normalize_sqlite_request(
         "runAs": _run_as(run_as) if run_as is not None else None,
         "databaseFile": _database_file(database_file) if database_file is not None else None,
         "sourceDatabase": _source_database(source_database) if source_database is not None else None,
+        "recoveryScope": normalize_recovery_scope(recovery_scope),
     }
     if request["sourceDatabase"] is not None:
         if request["runAs"] is None or request["databaseFile"] is None:
@@ -140,6 +143,7 @@ def _b64(value: str) -> str:
 def build_remote_script(spec: dict[str, Any] | None = None) -> str:
     spec = spec or {}
     env = spec.get("maintenanceEnvironment", {})
+    recovery_payload = json.dumps(spec.get("recoveryEvidence", {}), sort_keys=True, separators=(",", ":"))
     replacements = {
         "__APP_ROOT__": APP_ROOT,
         "__SQLITE_SCHEMA_VERSION__": str(SQLITE_SCHEMA_VERSION),
@@ -154,6 +158,7 @@ def build_remote_script(spec: dict[str, Any] | None = None) -> str:
         "__RESERVATION_SHA__": spec.get("reservationSha256", ""),
         "__ENV_KEYS__": " ".join(f"'{_b64(k)}'" for k in env),
         "__ENV_VALUES__": " ".join(f"'{_b64(v)}'" for v in env.values()),
+        "__RECOVERY_EVIDENCE_B64__": _b64(recovery_payload),
     }
     script = REMOTE_SCRIPT
     for placeholder, value in replacements.items():
@@ -291,6 +296,12 @@ def plan_sqlite_operation(
         spec.update(runAs=existing["runAs"], databaseFile=existing["databaseFile"], reservationSha256=existing["reservationSha256"])
         if action in {"backup", "migrate", "rollback-check"} and not existing["databasePresent"]:
             raise DeploymentKitError(f"SQLite {action} requires an existing database.")
+    creates_verified_backup = bool(action == "backup" or (action == "migrate" and not request["firstInstall"]))
+    recovery_scope = request["recoveryScope"]
+    spec["recoveryEvidence"] = recovery_evidence(
+        recovery_scope,
+        database_backup_verified=creates_verified_backup,
+    )
     return {
         "targetName": name, "action": action, "ownerRepo": request["ownerRepo"],
         "environment": request["environment"], "productionClassified": production_classified,
@@ -299,7 +310,10 @@ def plan_sqlite_operation(
         "sourceDatabase": request["sourceDatabase"] if action == "import" else None,
         "firstInstall": bool(request["firstInstall"] if action == "migrate" else False),
         "stopsManagedRuntime": bool(action == "migrate" and existing and existing["managedRuntimeRunning"]),
-        "createsVerifiedBackup": bool(action == "backup" or (action == "migrate" and not request["firstInstall"])),
+        "createsVerifiedBackup": creates_verified_backup,
+        "verifiedBackupScope": "database" if creates_verified_backup else None,
+        "recoveryScope": public_recovery_scope(recovery_scope),
+        "applicationRecoveryReadyAfterOperation": False,
         "inventorySnapshot": _snapshot(inventory), "expectedReservationSha256": expected_sha, "spec": spec,
     }
 
@@ -319,11 +333,18 @@ def authorization_phrase(plan: dict[str, Any]) -> str:
 
 
 def apply_sqlite_operation(plan: dict[str, Any]) -> dict[str, Any]:
-    required = {"targetName", "action", "ownerRepo", "environment", "productionClassified", "appSlug", "image", "databaseFile", "runAs", "sourceDatabase", "firstInstall", "stopsManagedRuntime", "createsVerifiedBackup", "inventorySnapshot", "expectedReservationSha256", "spec"}
+    required = {
+        "targetName", "action", "ownerRepo", "environment", "productionClassified", "appSlug", "image",
+        "databaseFile", "runAs", "sourceDatabase", "firstInstall", "stopsManagedRuntime", "createsVerifiedBackup",
+        "verifiedBackupScope", "recoveryScope", "applicationRecoveryReadyAfterOperation", "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.")
+    if plan["applicationRecoveryReadyAfterOperation"] is not False:
+        raise DeploymentKitError("SQLite operations cannot claim application recovery readiness.")
     _require_ready_platform(plan["targetName"])
     current = sqlite_inventory(plan["targetName"])
     if _snapshot(current) != plan["inventorySnapshot"]:
@@ -334,6 +355,10 @@ def apply_sqlite_operation(plan: dict[str, Any]) -> dict[str, Any]:
     result["mutated"] = True
     result["operation"] = plan["action"]; result["operationOutput"] = output.strip()
     result["productionClassified"] = plan["productionClassified"]
+    result["recoveryReadiness"] = recovery_readiness(
+        plan["spec"]["recoveryScope"],
+        database_backup_verified=plan["createsVerifiedBackup"],
+    )
     return result
 
 

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

@@ -19,6 +19,7 @@ FIRST_INSTALL="__FIRST_INSTALL__"
 RESERVATION_SHA="__RESERVATION_SHA__"
 ENV_KEYS=(__ENV_KEYS__)
 ENV_VALUES=(__ENV_VALUES__)
+RECOVERY_EVIDENCE_B64="__RECOVERY_EVIDENCE_B64__"
 
 b64d() { printf '%s' "$1" | base64 --decode; }
 meta_value() {
@@ -121,6 +122,7 @@ decode_spec() {
     RUN_AS="$(b64d "$RUN_AS_B64")"
     DATABASE_FILE="$(b64d "$DB_FILE_B64")"
     SOURCE_DATABASE="$(b64d "$SOURCE_DB_B64")"
+    RECOVERY_EVIDENCE_JSON="$(b64d "$RECOVERY_EVIDENCE_B64")"
     valid_repo "$OWNER" || { echo "Invalid SQLite owner repository." >&2; exit 45; }
     valid_slug "$ENVIRONMENT" || { echo "Invalid SQLite environment." >&2; exit 45; }
     valid_slug "$APP_SLUG" || { echo "Invalid SQLite app slug." >&2; exit 45; }
@@ -129,6 +131,7 @@ decode_spec() {
     valid_db_file "$DATABASE_FILE" || { echo "Invalid SQLite database file name." >&2; exit 45; }
     [[ "$RESERVATION_SHA" =~ ^[0-9a-f]{64}$ ]] || { echo "Invalid SQLite reservation fingerprint." >&2; exit 45; }
     [[ "${#ENV_KEYS[@]}" -eq "${#ENV_VALUES[@]}" && "${#ENV_KEYS[@]}" -gt 0 ]] || { echo "Invalid SQLite maintenance environment payload." >&2; exit 45; }
+    [[ "$RECOVERY_EVIDENCE_JSON" == \{*\} ]] || { echo "Invalid SQLite recovery evidence payload." >&2; exit 45; }
     local index key
     for index in "${!ENV_KEYS[@]}"; do
         key="$(b64d "${ENV_KEYS[$index]}")"
@@ -210,8 +213,8 @@ run_migrate() {
 record_evidence() {
     local root="$1" action="$2" outcome="$3" artifact="${4:-}" timestamp
     timestamp="$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
-    printf '{"timestamp":"%s","action":"%s","ownerRepo":"%s","environment":"%s","appSlug":"%s","image":"%s","databaseFile":"%s","reservationSha256":"%s","artifact":"%s","outcome":"%s"}\n' \
-        "$timestamp" "$action" "$OWNER" "$ENVIRONMENT" "$APP_SLUG" "$IMAGE" "$DATABASE_FILE" "$RESERVATION_SHA" "$artifact" "$outcome" >> "$root/sqlite-evidence.jsonl"
+    printf '{"timestamp":"%s","action":"%s","ownerRepo":"%s","environment":"%s","appSlug":"%s","image":"%s","databaseFile":"%s","reservationSha256":"%s","artifact":"%s","outcome":"%s","recovery":%s}\n' \
+        "$timestamp" "$action" "$OWNER" "$ENVIRONMENT" "$APP_SLUG" "$IMAGE" "$DATABASE_FILE" "$RESERVATION_SHA" "$artifact" "$outcome" "$RECOVERY_EVIDENCE_JSON" >> "$root/sqlite-evidence.jsonl"
     chmod 0600 "$root/sqlite-evidence.jsonl"
 }
 
@@ -287,7 +290,7 @@ operate() {
             backup_name="backup-$stamp-$DATABASE_FILE"
             run_backup "$DATA" "$BACKUPS" "$backup_name"
             record_evidence "$ROOT" backup backed-up "$backup_name"
-            printf 'SQLite verified backup created: %s\n' "$BACKUPS/$backup_name"
+            printf 'SQLite verified database backup created: %s\n' "$BACKUPS/$backup_name"
             ;;
         migrate)
             if [[ "$FIRST_INSTALL" == true ]]; then
@@ -311,12 +314,12 @@ operate() {
                 if [[ "$MANAGED_RUNNING" == true ]]; then docker stop "$MANAGED_CONTAINER" >/dev/null; fi
                 if ! run_migrate "$DATA"; then
                     record_evidence "$ROOT" migrate failed "$backup_name"
-                    echo "SQLite migration failed; verified pre-migration backup is retained and managed runtime remains stopped." >&2
+                    echo "SQLite migration failed; verified pre-migration database backup is retained and managed runtime remains stopped." >&2
                     exit 50
                 fi
                 run_check "$DATA"
                 record_evidence "$ROOT" migrate migrated "$backup_name"
-                printf 'SQLite migration completed; verified pre-migration backup: %s\n' "$BACKUPS/$backup_name"
+                printf 'SQLite migration completed; verified pre-migration database backup: %s\n' "$BACKUPS/$backup_name"
             fi
             ;;
         rollback-check)
@@ -337,4 +340,4 @@ case "$ACTION" in
     import|backup|migrate|rollback-check) operate ;;
     *) echo "Unsupported SQLite adapter action: $ACTION" >&2; exit 2 ;;
 esac
-'''
+'''

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

@@ -1,6 +1,7 @@
 """CLI for the SQLite persistence adapter."""
 from __future__ import annotations
 import argparse, json, sys
+from pathlib import Path
 from typing import Any
 from .errors import DeploymentKitError
 from .sqlite_adapter import authorization_phrase, apply_sqlite_operation, normalize_sqlite_request, plan_sqlite_operation, sqlite_inventory
@@ -28,6 +29,18 @@ def _parse_env(items: list[str]) -> list[tuple[str,str]]:
     return out
 
 
+def _load_recovery_manifest(path: str | None) -> dict[str, Any] | None:
+    if path is None:
+        return None
+    try:
+        value = json.loads(Path(path).read_text(encoding='utf-8'))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(f"Could not read recovery manifest as UTF-8 JSON: {error}") from error
+    if not isinstance(value, dict):
+        raise DeploymentKitError("Recovery manifest root must be a JSON object.")
+    return value
+
+
 def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
     if args.yes: return
     if input(f"Type {phrase} to {action}: ").strip() != phrase:
@@ -50,6 +63,10 @@ def _common(parser: argparse.ArgumentParser) -> None:
     parser.add_argument('--yes', action='store_true')
 
 
+def _recovery_manifest_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument('--recovery-manifest', help='Optional strict non-secret JSON declaration of recovery dependencies and authentication policy')
+
+
 def _import_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument('--run-as', required=True)
     parser.add_argument('--database-file', required=True)
@@ -62,8 +79,8 @@ def build_parser() -> argparse.ArgumentParser:
     inv=sub.add_parser('inventory',help='Read SQLite persistence reservations without writes'); inv.add_argument('name'); inv.add_argument('--json',action='store_true')
     imp=sub.add_parser('import',help='Import an existing SQLite DB via the exact image online-backup contract'); _common(imp); _import_args(imp)
     recover=sub.add_parser('recover-import',help='Recover a verified failed import without overwriting or recopying the database'); _common(recover); _import_args(recover)
-    backup=sub.add_parser('backup',help='Create a verified SQLite backup with the exact image'); _common(backup)
-    migrate=sub.add_parser('migrate',help='Create required backup and run exact-image SQLite migration'); _common(migrate)
+    backup=sub.add_parser('backup',help='Create a verified SQLite database backup with the exact image'); _common(backup); _recovery_manifest_arg(backup)
+    migrate=sub.add_parser('migrate',help='Create required database backup and run exact-image SQLite migration'); _common(migrate); _recovery_manifest_arg(migrate)
     migrate.add_argument('--first-install',action='store_true'); migrate.add_argument('--run-as'); migrate.add_argument('--database-file')
     check=sub.add_parser('rollback-check',help='Verify that an exact rollback image accepts the current SQLite state'); _common(check)
     return parser
@@ -73,10 +90,13 @@ 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
+        if args.command=='migrate' and getattr(args,'first_install',False) and getattr(args,'recovery_manifest',None):
+            raise DeploymentKitError("--recovery-manifest is supported only for existing-database SQLite migration, not --first-install.")
         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))
+            source_database=getattr(args,'source_database',None),first_install=getattr(args,'first_install',False),
+            recovery_scope=_load_recovery_manifest(getattr(args,'recovery_manifest',None)))
         if args.command=='recover-import':
             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)

package/package.json

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