@mriekki/project-forge 4.7.0 → 4.8.1

package/README.md

@@ -103,28 +103,17 @@ The stable descriptor at `chatgpt/current.json` resolves an immutable Project Fo
 
 `@mriekki/project-forge` is the public distribution for Project Forge engineering assets used by generated projects.
 
-Project Forge assembles that package from approved private platform components using exact pinned source commits and deterministic distribution descriptors. Published packages are self-contained; Builders do not need access to the private implementation repositories to install or update managed assets.
+Project Forge assembles that package from approved private platform components using exact pinned source revisions and deterministic distribution descriptors. Published packages are self-contained; Builders do not need access to the private implementation repositories to install or update managed assets.
 
-Install:
+Generated Projects receive an exact approved package during deterministic generation. Existing generated Projects should normally adopt a newer supported package through:
 
-```powershell
-npx @mriekki/project-forge install
-```
-
-Update to the newest published package:
-
-```powershell
-npx @mriekki/project-forge@latest update
+```text
+/project-forge-update
 ```
 
-Inspect and verify:
-
-```powershell
-npx @mriekki/project-forge@latest status
-npx @mriekki/project-forge@latest check
-```
+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.
 
-Managed updates verify baselines and refuse unsafe drift or conflicts before modifying Project Forge-managed files.
+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
 
@@ -137,7 +126,7 @@ The system reference deliberately does not duplicate current component SHAs, pac
 
 ## 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.
+Project Forge maintainers use a gated release workflow that resolves accepted component revisions, verifies the assembled package, creates the package pull request, verifies CI, and stops at the explicit publication gate.
 
 Publication uses npm Trusted Publishing (OIDC), reconstructs the exact package from pinned sources, verifies registry identity and integrity, and smoke-tests the public package from a neutral directory.
 

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.7.0",
+  "version": "4.8.1",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,7 +13,7 @@
   },
   "components": {
     "core": {
-      "revision": "737dab0636252410c022be057d25c36c1dd5f116",
+      "revision": "a78c2482f4f559ead8efbab6c25b4b05496db735",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "f7441081114be94a22d6e1774194dc8bd7a88e18",
+      "revision": "aaf5d24c897b3d89b3d1791c79bed4979414ca40",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/generated/ASSEMBLY.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.7.0",
+  "version": "4.8.1",
   "components": {
     "core": {
-      "revision": "737dab0636252410c022be057d25c36c1dd5f116",
+      "revision": "a78c2482f4f559ead8efbab6c25b4b05496db735",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -116,12 +116,12 @@
         {
           "source": "core/skills/deployment-readiness/SKILL.md",
           "destination": ".github/skills/deployment-readiness/SKILL.md",
-          "sha256": "33be75e856b1b16378bb2a456d8418f8ae0b03edee75fb826d8f7ef3824d2f6a"
+          "sha256": "30202702cc368c872e62ce731e8ffe84a796aae243b287e3e670c8c8e1cd6531"
         },
         {
           "source": "core/skills/deploy/SKILL.md",
           "destination": ".github/skills/deploy/SKILL.md",
-          "sha256": "21b8209bc756ef2981f9e44f19ee80e79c1c5c7d5be4c03c9b528fdadd7b8eca"
+          "sha256": "f5d40e549ca958cb51606ced7ca482651d9a436327b6070a9a94171f22401700"
         },
         {
           "source": "core/skills/tear-down/SKILL.md",
@@ -326,7 +326,7 @@
       ]
     },
     "deployment": {
-      "revision": "f7441081114be94a22d6e1774194dc8bd7a88e18",
+      "revision": "aaf5d24c897b3d89b3d1791c79bed4979414ca40",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -357,12 +357,12 @@
         {
           "source": "src/project_forge_deployment/app_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_cli.py",
-          "sha256": "9bf8eb7337c5b506311bf718de71b9a2c9ac445eb94cb7dfdeb63a09e5f0f899"
+          "sha256": "f27704c80b1eff45888bf56745bcf8755f2fad88851147600af7056953757825"
         },
         {
           "source": "src/project_forge_deployment/app_deployment.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_deployment.py",
-          "sha256": "e58158e48c9fbd51b51f7af90f2dd178987ad3936e44507523cfc41b96fcd9f9"
+          "sha256": "606d6a4793ac8c8a95da4cd4c61792c69f02ad86900be1944d2ed570dd71e73e"
         },
         {
           "source": "src/project_forge_deployment/app_runtime.py",
@@ -502,12 +502,12 @@
         {
           "source": "src/project_forge_deployment/registry_access.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/registry_access.py",
-          "sha256": "5815a1921ecf37dc395f9c68b1ebda2b17dd6a44620b2356d1adff5df44c4382"
+          "sha256": "1f582f1b5da656579625748b13c779f6d67ed6a6049f0ebb104ce8c3f9185a4b"
         },
         {
           "source": "src/project_forge_deployment/registry_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/registry_cli.py",
-          "sha256": "1936156eb3b6103895795cde3b5f520491e407bf35f311be883a54fbfff635fc"
+          "sha256": "2ce977fa570580407c04a3e59d0a524f128af420b7ee20fd9706e6452378b7b3"
         },
         {
           "source": "src/project_forge_deployment/route_registry.py",

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

@@ -44,7 +44,7 @@ Read only what is needed, including when present:
 - `PROJECT_FORGE_BASELINE.json`;
 - `DEPLOYMENT_BASELINE.json`;
 - project topology and approved deployment/release requirements;
-- `/deployment-readiness` evidence, including deterministic application isolation evidence when supported;
+- `/deployment-readiness` evidence, including first-application outcome assessment and deterministic application isolation evidence when supported;
 - fresh setup-time environment-proof evidence for this workstation;
 - established application deployment facts.
 
@@ -62,7 +62,27 @@ Proof does not establish the real application's image/release, persistence/migra
 
 A prior readiness isolation fingerprint is review evidence only. It does not authorize deployment and does not replace the deterministic deployment planner's current isolation revalidation.
 
-## 3. First real deployment asks only unresolved application questions
+For a first real deployment, do not collapse a target/platform `READY` result into application deployability. Confirm that readiness established an actual artifact build/publication/acquisition path when that path is material. If artifact identity or acquisition is still hypothetical, return to the missing prerequisite rather than requesting the application write gate.
+
+## 3. Preserve execution and credential context
+
+When installed tooling exposes structured capability evidence, preserve its semantics exactly in the deployment assessment and preview. In particular, retain fields equivalent to:
+
+```text
+executionLocation
+credentialContext
+capabilityProved
+capabilityAttempted
+doesNotProve
+```
+
+A registry manifest check executed on a remote target proves only the capability reported for that target/context. Never describe it as workstation registry access. A workstation registry check proves only the workstation capability it reports. Neither implies Actions registry transport or package-metadata API access.
+
+Do not infer provider-specific token scopes or error meaning from generic registry results. Provider-specific package metadata/publication behavior belongs to repository/provider tooling and its own evidence.
+
+When a new credential is genuinely required, explain its purpose, execution context, storage location, retrievability, and rotation impact before asking the developer to create it. Credential values remain in the provider/local secret surface and never enter chat.
+
+## 4. First real deployment asks only unresolved application questions
 
 The first real `/deploy <environment>` after environment proof may need a small application-specific completion step. Ask only material unknowns not already answered by project evidence, such as:
 
@@ -79,7 +99,7 @@ When a bounded choice is useful, follow `INTERACTIVE_SESSION_GUIDE.md`: use host
 
 Once these facts are durably established, later deployments should be routine rather than repeating onboarding.
 
-## 4. Placement determines launcher
+## 5. Placement determines launcher
 
 ### Workstation container
 
@@ -114,7 +134,7 @@ Use only an installed repository/catalog provider adapter. If none exists, stop
 
 Report `DEPLOYMENT NOT BOUND YET` and route to `/setup <environment>` or `/deployment-readiness <environment>`.
 
-## 5. Preserve custom Production classification
+## 6. Preserve custom Production classification
 
 Pass the exact configured environment name to the deterministic launcher.
 
@@ -126,7 +146,7 @@ When resolved purpose/classification is Production, use the installed tool's exp
 
 Inspect installed help/version evidence. If the installed tool cannot preserve Production classification for a custom name, stop rather than downgrading safety.
 
-## 6. Build the deterministic plan
+## 7. Build the deterministic plan
 
 Use repository-provided tooling to construct/inspect the exact application deployment plan. Supported operations may include:
 
@@ -149,7 +169,44 @@ The deterministic deployment tool owns the final current-state recheck immediate
 
 Do not smuggle infrastructure provisioning, target/provider rebinding, destructive restore, or environment tear-down into the application plan.
 
-## 7. Preserve exact authorization contracts
+### Remote runtime + route rollout preview
+
+When the installed Deployment Kit exposes a deterministic read-only `app rollout` capability and the selected remote deployment has an intended route, prefer that capability for the final pre-write preview rather than independently narrating runtime and route consequences.
+
+A current installed contract may expose a command shape similar to:
+
+```text
+project-forge-deploy app rollout <target>
+  --owner-repo <owner/repository>
+  --environment <exact environment>
+  --app-slug <application slug>
+  --container-name <container>
+  --runtime-port <port>
+  --persistence-mode <none|directory>
+  --image <immutable digest>
+  --health-path <path>
+  --run-as <uid[:gid]>
+  [--route-hostname <hostname> ...]
+  [--production]
+  --json
+```
+
+Inspect installed help/version rather than assuming this example exactly matches every package version.
+
+Treat the returned staged rollout as **read-only review evidence**. Preserve:
+
+```text
+runtime plan + isolation evidence
+route plan + route-inventory evidence
+separate stage authorizations
+endpoint state before runtime
+after-runtime / before-route endpoint state
+after-route verification state
+```
+
+If the installed package lacks this composite preview, retain the existing safe runtime and route planners and state their sequence explicitly. Do not invent a combined write command.
+
+## 8. Preserve exact authorization contracts
 
 Core consequence labels do not replace stricter installed-tool phrases.
 
@@ -158,17 +215,20 @@ The standard Deployment Kit may use exact phrases such as:
 ```text
 [APP DEPLOY WRITE]
 [PRODUCTION APP DEPLOY]
+[ROUTE WRITE]
 ```
 
 For Production-class environments also show `[PRODUCTION WRITE]` consequence visibility where Core policy calls for it.
 
-Resolve the exact phrase from the installed tool/version. Do not assume an example phrase when the installed contract differs.
+Resolve the exact phrase from the installed tool/version. For a staged rollout, resolve it separately for each stage. Do not assume an example phrase when the installed contract differs.
+
+Authorization applies only to the exact environment, resolved classification, placement/target/provider, artifact, reviewed plan/stage, current isolation evidence and route evidence, and evidence shown. Material changes require renewed review/authorization.
 
-Authorization applies only to the exact environment, resolved classification, placement/target/provider, artifact, reviewed plan, current isolation evidence, and evidence shown. Material changes require renewed review/authorization.
+A runtime authorization never authorizes the route stage. A route authorization never retroactively authorizes a changed runtime artifact. If the rollout contains both stages, preserve the separate gates even though the Builder reviewed one coherent outcome.
 
-## 8. Preview and execute only the approved contract
+## 9. Preview and execute only the approved contract
 
-Before mutation, show concise non-secret evidence such as exact environment, purpose, placement, target/provider when applicable, proof freshness, immutable application artifact, persistence/migration, exposure/route, application isolation state/fingerprint when exposed, shared failure-domain note when relevant, planned operations, and exact required authorization phrase.
+Before mutation, show concise non-secret evidence such as exact environment, purpose, placement, target/provider when applicable, proof freshness, immutable application artifact, persistence/migration, exposure/route, application isolation state/fingerprint when exposed, shared failure-domain note when relevant, planned stages, endpoint state at each stage, and the exact required authorization phrase for the next consequence only.
 
 After authorization, invoke only the repository-provided deterministic launcher. Never redirect to another environment/host/provider, weaken trust/exposure, force through lock contention, or invent recovery writes.
 
@@ -176,7 +236,37 @@ The deterministic launcher must revalidate current isolation immediately before
 
 Existing per-app/per-environment locks are normal concurrency protection when another workstation is deploying the same environment.
 
-## 9. Validate live evidence
+### Runtime succeeded but route is pending
+
+A healthy application runtime is a valid intermediate outcome. When a requested route has not yet been registered, say this explicitly before showing the route gate:
+
+```text
+APPLICATION RUNTIME READY
+Expected endpoint: <hostname/URL>
+Endpoint state: NOT ACTIVE — ROUTE PENDING
+Do not test this URL yet; the route write has not been authorized/applied.
+```
+
+Then, if the reviewed route plan is still current, present the route consequence directly. Do not require the developer to invoke `/deploy` or another slash command merely to rediscover the already reviewed route stage.
+
+The runtime success does not consume or imply route authorization. If route evidence changed, rebuild/review the route plan first.
+
+## 10. Resume the established outcome without navigation ceremony
+
+Within the same conversation, if a bounded engineering/delivery correction or external prerequisite completes and the developer's requested deployment outcome remains unambiguous, automatically resume safe **read-only** reconstruction of readiness/deployment evidence from the repository, GitHub, installed tools, and runtime state.
+
+Do not require the developer to type `/deliver`, `/deployment-readiness`, or `/deploy` merely as navigation to rediscover known state after that bounded action completes.
+
+This continuation:
+
+- never repeats a completed write;
+- never reuses exhausted registry/Production/route/merge/migration/destructive authority;
+- stops when the artifact, plan, target, consequence, or other material evidence changed;
+- does not create a parallel persistent workflow database.
+
+If `/deploy` is invoked again after an already validated deployment, first reconstruct current deployment evidence. If the same validated artifact/runtime/route remains current and no new deployment outcome is requested, report the existing validated state rather than proposing or performing a redundant redeployment.
+
+## 11. Validate live evidence
 
 After execution, use repository-provided inventory/health/route/smoke/evidence commands when available.
 
@@ -191,10 +281,32 @@ Artifact: <exact immutable identity>
 Artifact delivery: <workstation-transfer|remote-registry|local-runtime|provider>
 Endpoint/Route: READY / LOOPBACK / NOT APPLICABLE
 Application health: READY
+Workstation/browser verification: PASSED / NOT APPLICABLE / PENDING
 Smoke: PASSED / NOT REQUIRED
 Deployment evidence: RECORDED / VERIFIED
 ```
 
-Do not report success merely because a container/process started when stronger health evidence is required.
+Do not report success merely because a container/process started when stronger health evidence is required. Do not report a route as user-accessible merely because registration returned; perform the repository-supported endpoint/workstation/browser verification when the requested outcome depends on it.
 
 A setup-time disposable environment proof is not real application deployment evidence. A successful application deployment never authorizes a later Production write or destructive `/tear-down`.
+
+Keep human access confirmation distinct from automated browser/health evidence. The developer saying they can reach the endpoint is useful observed human evidence; it is not automatically formal work-item acceptance.
+
+## 12. Reconcile the durable outcome without asserting acceptance
+
+After `DEPLOYMENT VALIDATED`, inspect the repository's configured work-item/operating authority. When an existing current-status or deployment-result section is stale and the observed deployment outcome is material, offer a bounded reconciliation containing only supported non-secret facts such as:
+
+```text
+exact environment
+release/source/artifact identity
+artifact delivery method
+runtime health result
+route/endpoint
+workstation/browser validation
+explicit human access confirmation, when actually stated
+known limitations and evidence boundaries
+```
+
+Preserve historical approval records. Do not silently rewrite product requirements, broaden the milestone, mark formal acceptance, close the work item, or infer acceptance from browser accessibility.
+
+If the human authorizes the bounded documentation update, use the repository's normal work-item/delivery workflow for that edit. Documentation reconciliation is not a reason to redeploy and does not create new Production write authority.

package/assets/generated/core/core/skills/deployment-readiness/SKILL.md

@@ -78,7 +78,78 @@ It does not prove final application artifact identity, persistence/migration beh
 
 If topology, target binding, host trust, platform state, or another material fact changes, treat the proof as stale and reverify the affected prerequisite.
 
-## 3. Placement branches
+## 3. First-application outcome assessment
+
+For the first real application deployment to an environment, or whenever the developer's stated goal is a usable endpoint rather than only machine readiness, keep that requested outcome visible and assess the whole material path before declaring the application deploy-ready.
+
+Inspect available non-secret repository, package/tool, workstation, target, and GitHub/CI evidence before asking for facts. Do not require a release workflow to fail merely to discover a prerequisite that can be identified read-only.
+
+Build a compact prerequisite matrix with rows such as:
+
+```text
+requested outcome / expected endpoint
+workstation architecture
+required artifact/target architecture
+immutable artifact or release identity policy
+artifact destination / publication state when relevant
+credential capability + execution location for each required operation
+workstation artifact acquisition capability
+target delivery method
+current application isolation / footprint
+runtime health contract
+route / exposure mechanism
+final workstation/browser verification
+```
+
+For each material row distinguish:
+
+```text
+evidence source
+execution location / credential context
+PROVEN / UNKNOWN / BLOCKED / NOT APPLICABLE
+missing fact or prerequisite
+exact consequential gate, if any
+effect on the requested endpoint
+```
+
+Architecture is a portability fact, not an operating-system stereotype. For example, an ARM64 workstation targeting a Linux/x86-64 environment must surface the required artifact platform explicitly; do not label that generically as a macOS defect.
+
+Do not report `ENVIRONMENT READY TO DEPLOY` for the first real application while its actual artifact build/publication/acquisition path is still hypothetical. Target/platform readiness and application-deployment readiness are different dimensions.
+
+Keep these evidence dimensions separate in status language:
+
+```text
+static/review correctness
+live external-contract confidence
+credential capability in the exact execution context
+immutable artifact provenance
+environment/runtime readiness
+route state
+workstation/browser validation
+human access confirmation
+formal work-item acceptance
+```
+
+A green result in one dimension never proves another.
+
+### Credential capability and lifecycle
+
+Reason from **operation + execution context**, not from the existence of a generic token or successful access somewhere else. When installed tooling exposes structured registry capability evidence, preserve fields such as execution location, credential context, capability proved, and `doesNotProve` rather than paraphrasing a target result as workstation access.
+
+Before asking the developer to create or rotate a credential, explain non-secret lifecycle facts first:
+
+```text
+purpose / capability
+machine, workflow, or process where it is used
+where the credential will be stored
+whether its value can be retrieved again
+rotation/regeneration impact on existing consumers
+value must remain in the local/provider secret surface, never chat
+```
+
+Do not assume registry transport access proves package-metadata API access, that target registry access proves workstation access, or that a workstation login proves an Actions workflow capability. Provider-specific token types, scopes, and error-body strings belong to installed/provider-owned adapters or Project evidence, not generic Core invention.
+
+## 4. Placement branches
 
 ### A. Workstation placement
 
@@ -188,7 +259,7 @@ DEPLOYMENT INTENTIONALLY DEFERRED
 
 Do not mark workspace readiness failed. Route to `/setup <environment>` or `/setup remote` if the developer later wants to bind it.
 
-## 4. Shared failure domains / colocated environments
+## 5. Shared failure domains / colocated environments
 
 Multiple logical environments may share physical failure domains, but they remain independently targetable and independently authorized. If environments share physical failure, state it explicitly.
 
@@ -196,7 +267,7 @@ A clear application isolation preflight means the current Deployment Kit-managed
 
 Colocation does not demonstrate host-level Production isolation. Never infer readiness for one logical environment from another merely because they share hardware.
 
-## 5. State-driven cadence
+## 6. State-driven cadence
 
 Normal cadence is:
 
@@ -205,6 +276,7 @@ select exact project-defined environment
 → read current topology
 → reuse fresh environment-proof evidence when valid
 → rediscover placement-relevant local state
+→ for first real deployment, assess the complete artifact/credential/delivery/route/endpoint path
 → verify current application isolation when the installed adapter supports it
 → verify/repair only missing prerequisites under exact gates
 → ENVIRONMENT READY TO DEPLOY
@@ -213,7 +285,9 @@ select exact project-defined environment
 
 For remote placement, reuse valid existing target access rather than creating duplicate credentials simply because another Project/environment uses the same machine.
 
-## 6. Read-only status
+When a bounded engineering/delivery correction completes in the same conversation and the developer's deployment outcome is still clear, automatically resume safe read-only readiness reconstruction from current repository/tool evidence. Do not require the developer to type `/deployment-readiness` again merely as navigation. This continuation does not reuse an exhausted write authorization and does not authorize a new registry, Production, route, migration, merge, or other consequential write.
+
+## 7. Read-only status
 
 `/deployment-readiness status [environment]` performs no remote writes. Without a specific environment, summarize all known environments from project topology, including Placement and deferred state where evidenced.
 
@@ -229,7 +303,7 @@ Archive       demo         deferred       NOT APPLICABLE           DEFERRED
 
 Do not manufacture target/provider facts for deferred environments.
 
-## 7. Bounded readiness writes
+## 8. Bounded readiness writes
 
 A missing prerequisite is not authorization to change it. Use the repository/tool's exact authorization phrase for key/trust/platform/provider mutations.
 
@@ -237,21 +311,23 @@ Do not hide the real application deployment inside readiness. Readiness may rely
 
 The application isolation preflight itself is read-only and does not authorize later deployment, route, persistence, migration, Production, or destructive writes.
 
-## 8. Pre-deploy versus post-deploy evidence
+## 9. Pre-deploy versus post-deploy evidence
 
 Readiness asks whether `/deploy <name>` can safely perform the real application deployment now.
 
-Pre-deploy evidence may include topology, adapter availability, binding, local/remote identity and access, target platform, fresh proof evidence, artifact policy, deterministic application isolation/collision evidence, route/port availability, persistence/backup/migration prerequisites, lock/recovery capability, and Production-specific safeguards.
+Pre-deploy evidence may include topology, adapter availability, binding, local/remote identity and access, target platform, fresh proof evidence, artifact policy, actual artifact acquisition/publication capability when material, deterministic application isolation/collision evidence, route/port availability, persistence/backup/migration prerequisites, lock/recovery capability, and Production-specific safeguards.
 
 Do not require first-deployment live route, deployed-release identity, application health, or smoke evidence before the application has ever been deployed. Those are post-deploy validation evidence owned by `/deploy`.
 
-## 9. Production policy
+The intended endpoint may still be known before deployment. When the route does not yet exist, label it explicitly `NOT ACTIVE — ROUTE PENDING`; do not invite the developer to test it as though readiness had made it reachable.
+
+## 10. Production policy
 
 Production is logical policy, not hardware count and not the literal name `production`. A named environment such as `prod-east` with purpose `production` must retain Production readiness and later deployment gates.
 
 Readiness never authorizes Production application deployment.
 
-## 10. Final handoff
+## 11. Final handoff
 
 When pre-deploy requirements are satisfied:
 
@@ -263,10 +339,14 @@ Purpose: <purpose>
 Placement: <...>
 Binding: VERIFIED / LOCAL / provider-specific
 This-workstation environment proof: PROVEN / NOT REQUIRED / NOT AVAILABLE
+Artifact path: PROVEN / NOT APPLICABLE
+Credential contexts: PROVEN / NOT APPLICABLE
 Application isolation: CLEAR / NOT APPLICABLE
 Isolation evidence: <evidenceSha256 when exposed by installed tooling>
 Platform prerequisites: READY
 Application-specific prerequisites: READY / <remaining items>
+Expected endpoint: <URL/route when known>
+Endpoint state: NOT ACTIVE — ROUTE PENDING / LOOPBACK PENDING / provider-specific
 Security blockers: NONE
 
 POST-DEPLOY VALIDATION PENDING

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

@@ -12,6 +12,7 @@ from .app_deployment import (
     apply_app_deploy,
     apply_app_deploy_from_workstation,
     plan_app_deploy,
+    plan_app_rollout,
 )
 from .app_runtime import (
     APP_DEPLOY_WRITE_PHRASE,
@@ -85,6 +86,29 @@ def _add_isolation_footprint(parser: argparse.ArgumentParser) -> None:
     )
 
 
+def _add_runtime_contract(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--image", required=True)
+    parser.add_argument("--health-path", required=True)
+    parser.add_argument("--run-as", required=True)
+    parser.add_argument("--data-container-path")
+    parser.add_argument(
+        "--env",
+        action="append",
+        default=[],
+        help="Non-secret runtime environment value in NAME=value form; repeat as needed",
+    )
+    parser.add_argument(
+        "--image-source",
+        choices=("remote-registry", "workstation"),
+        default="remote-registry",
+        help=(
+            "remote-registry preserves the existing target-side pull path; workstation streams an exact local image "
+            "over verified SSH so the target does not need registry credentials"
+        ),
+    )
+    parser.add_argument("--json", action="store_true")
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="project-forge-deploy app")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -108,31 +132,19 @@ def build_parser() -> argparse.ArgumentParser:
     )
     isolation.add_argument("--json", action="store_true")
 
+    rollout = sub.add_parser(
+        "rollout",
+        help="Preview application runtime and owned route as one read-only staged rollout",
+    )
+    _add_isolation_footprint(rollout)
+    _add_runtime_contract(rollout)
+
     deploy = sub.add_parser(
         "deploy",
         help="Deploy one immutable application runtime without modifying routes",
     )
     _add_isolation_footprint(deploy)
-    deploy.add_argument("--image", required=True)
-    deploy.add_argument("--health-path", required=True)
-    deploy.add_argument("--run-as", required=True)
-    deploy.add_argument("--data-container-path")
-    deploy.add_argument(
-        "--env",
-        action="append",
-        default=[],
-        help="Non-secret runtime environment value in NAME=value form; repeat as needed",
-    )
-    deploy.add_argument(
-        "--image-source",
-        choices=("remote-registry", "workstation"),
-        default="remote-registry",
-        help=(
-            "remote-registry preserves the existing target-side pull path; workstation streams an exact local image "
-            "over verified SSH so the target does not need registry credentials"
-        ),
-    )
-    deploy.add_argument("--json", action="store_true")
+    _add_runtime_contract(deploy)
     deploy.add_argument("--yes", action="store_true")
     return parser
 
@@ -175,6 +187,20 @@ def main(argv: list[str] | None = None) -> int:
             environment_variables=_parse_env(args.env),
         )
         assert_app_spec_matches_persistence(args.name, spec)
+
+        if args.command == "rollout":
+            rollout_plan = plan_app_rollout(
+                args.name,
+                spec,
+                production=production_classified,
+                database_file=args.database_file,
+                route_hostnames=args.route_hostname,
+            )
+            rollout_plan["imageSource"] = args.image_source
+            rollout_plan["targetRegistryCredentialRequired"] = args.image_source == "remote-registry"
+            _print(rollout_plan, as_json=args.json)
+            return 0
+
         plan = plan_app_deploy(
             args.name,
             spec,

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

@@ -10,15 +10,19 @@ from __future__ import annotations
 
 from typing import Any, Iterable
 
+from .app_runtime import PRODUCTION_APP_DEPLOY_WRITE_PHRASE
 from .app_runtime import apply_app_deploy as _apply_runtime_deploy
+from .app_runtime import deploy_write_phrase
 from .app_runtime import plan_app_deploy as _plan_runtime_deploy
 from .app_runtime_workstation import apply_app_deploy_with_preloaded_image
 from .environment_isolation import environment_isolation_preflight
 from .errors import DeploymentKitError
 from .image_transfer import transfer_image
+from .route_registry import ROUTE_WRITE_PHRASE, plan_route_registration
 
 
 ISOLATION_REVIEW_KEY = "isolationReview"
+ROLLOUT_SCHEMA_VERSION = 1
 
 
 def app_isolation_check(
@@ -139,6 +143,100 @@ def plan_app_deploy(
     return plan
 
 
+def _endpoint_states(route_plan: dict[str, Any] | None) -> dict[str, str]:
+    if route_plan is None:
+        return {
+            "beforeRuntime": "NO_ROUTE_REQUESTED",
+            "afterRuntimeBeforeRoute": "NO_ROUTE_REQUESTED",
+            "afterRoute": "NO_ROUTE_REQUESTED",
+        }
+    if route_plan["changeType"] == "create":
+        before = "NOT_ACTIVE_ROUTE_ABSENT"
+        after_runtime = "NOT_ACTIVE_ROUTE_PENDING"
+    else:
+        before = "ROUTE_PRESENT_RUNTIME_STATE_NOT_VALIDATED"
+        after_runtime = "ROUTE_PRESENT_ROUTE_CHANGE_PENDING"
+    return {
+        "beforeRuntime": before,
+        "afterRuntimeBeforeRoute": after_runtime,
+        "afterRoute": "ROUTE_REGISTERED_BROWSER_VERIFICATION_PENDING",
+    }
+
+
+def plan_app_rollout(
+    target_name: str,
+    spec: dict[str, Any],
+    *,
+    production: bool = False,
+    database_file: str | None = None,
+    route_hostnames: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Compose read-only runtime and route plans into one staged rollout preview."""
+
+    hosts = list(route_hostnames or [])
+    app_plan = plan_app_deploy(
+        target_name,
+        spec,
+        production=production,
+        database_file=database_file,
+        route_hostnames=hosts,
+    )
+    route_plan = None
+    if hosts:
+        route_plan = plan_route_registration(
+            target_name,
+            owner_repo=spec["ownerRepo"],
+            environment=spec["environment"],
+            app_slug=spec["appSlug"],
+            upstream_container=spec["containerName"],
+            upstream_port=spec["runtimePort"],
+            hostnames=hosts,
+        )
+
+    runtime_authorization = (
+        PRODUCTION_APP_DEPLOY_WRITE_PHRASE
+        if production or spec["environment"] == "production"
+        else deploy_write_phrase(app_plan)
+    )
+    stages = [
+        {
+            "stage": "runtime",
+            "action": "deploy-application-runtime",
+            "requiredAuthorization": runtime_authorization,
+            "mutated": False,
+        }
+    ]
+    if route_plan is not None:
+        stages.append(
+            {
+                "stage": "route",
+                "action": "register-application-route",
+                "requiredAuthorization": ROUTE_WRITE_PHRASE,
+                "mutated": False,
+            }
+        )
+
+    runtime_view = {key: value for key, value in app_plan.items() if key != "spec"}
+    return {
+        "schemaVersion": ROLLOUT_SCHEMA_VERSION,
+        "targetName": target_name,
+        "environment": spec["environment"],
+        "production": bool(production or spec["environment"] == "production"),
+        "image": spec["image"],
+        "runtimePlan": runtime_view,
+        "routePlan": route_plan,
+        "stages": stages,
+        "separateAuthorizationsRequired": route_plan is not None,
+        "endpointState": _endpoint_states(route_plan),
+        "postRouteVerification": (
+            ["application-health", "route-http", "workstation-browser"]
+            if route_plan is not None
+            else ["application-health"]
+        ),
+        "mutated": False,
+    }
+
+
 def revalidate_app_isolation(plan: dict[str, Any]) -> dict[str, Any]:
     """Recheck the reviewed application footprint immediately before mutation."""
 
@@ -186,9 +284,11 @@ def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
 
 __all__ = [
     "ISOLATION_REVIEW_KEY",
+    "ROLLOUT_SCHEMA_VERSION",
     "app_isolation_check",
     "apply_app_deploy",
     "apply_app_deploy_from_workstation",
     "plan_app_deploy",
+    "plan_app_rollout",
     "revalidate_app_isolation",
 ]

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

@@ -1,7 +1,8 @@
-"""Read-only exact-image registry access verification for logical targets."""
+"""Read-only exact-image registry capability verification by execution context."""
 
 from __future__ import annotations
 
+import os
 import re
 import shlex
 import subprocess
@@ -13,6 +14,17 @@ from .ssh import ssh_args, verify_access
 
 
 _IMAGE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$")
+_REMOTE_DOES_NOT_PROVE = [
+    "workstation-registry-access",
+    "workstation-image-pull",
+    "actions-registry-transport",
+    "package-metadata-api-access",
+]
+_WORKSTATION_DOES_NOT_PROVE = [
+    "remote-target-registry-access",
+    "actions-registry-transport",
+    "package-metadata-api-access",
+]
 
 _REMOTE_SCRIPT = r'''#!/usr/bin/env bash
 set -Eeuo pipefail
@@ -61,6 +73,14 @@ printf 'ACCESS\t%s\n' "$credential_state"
 '''
 
 
+class RegistryCapabilityError(DeploymentKitError):
+    """Fail-closed registry capability error with safe structured evidence."""
+
+    def __init__(self, message: str, result: dict[str, Any]) -> None:
+        super().__init__(message)
+        self.result = result
+
+
 def normalize_registry_image(value: str) -> str:
     if not isinstance(value, str) or _IMAGE_RE.fullmatch(value) is None:
         raise DeploymentKitError(
@@ -83,13 +103,55 @@ def _parse_access(output: str) -> str:
     return parts[1]
 
 
+def _remote_failure_result(
+    *,
+    name: str,
+    image: str,
+    address: str,
+    returncode: int,
+) -> dict[str, Any]:
+    failure_codes = {
+        42: "docker-cli-unavailable",
+        43: "credential-config-unsafe",
+        44: "manifest-access-failed",
+    }
+    return {
+        "status": "failed",
+        "executionLocation": "remote-target",
+        "targetName": name,
+        "verifiedAddress": address,
+        "capabilityAttempted": "registry-manifest-read",
+        "image": image,
+        "failureCode": failure_codes.get(returncode, "remote-command-failed"),
+        "doesNotProve": list(_REMOTE_DOES_NOT_PROVE),
+        "mutated": False,
+    }
+
+
+def _workstation_failure_result(*, image: str, failure_code: str) -> dict[str, Any]:
+    return {
+        "status": "failed",
+        "executionLocation": "workstation",
+        "credentialContext": "workstation-docker-client",
+        "dockerConfigSource": "explicit-environment" if os.environ.get("DOCKER_CONFIG") else "default",
+        "capabilityAttempted": "registry-manifest-read",
+        "image": image,
+        "failureCode": failure_code,
+        "doesNotProve": list(_WORKSTATION_DOES_NOT_PROVE),
+        "mutated": False,
+    }
+
+
 def verify_registry_access(name: str, image: str) -> dict[str, Any]:
+    """Verify exact-image manifest access from the named remote target."""
+
     exact_image = normalize_registry_image(image)
     profile = load_profile(name)
     access = verify_access(profile)
+    address = access["address"]
     command = ssh_args(
         profile,
-        access["address"],
+        address,
         command="bash -s -- " + shlex.quote(exact_image),
     )
     completed = subprocess.run(
@@ -99,16 +161,84 @@ def verify_registry_access(name: str, image: str) -> dict[str, Any]:
         capture_output=True,
     )
     stdout = completed.stdout.decode("utf-8", errors="replace")
-    stderr = completed.stderr.decode("utf-8", errors="replace")
     if completed.returncode != 0:
-        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
-        raise DeploymentKitError(f"Read-only registry access verification failed: {detail}")
+        result = _remote_failure_result(
+            name=name,
+            image=exact_image,
+            address=address,
+            returncode=completed.returncode,
+        )
+        raise RegistryCapabilityError(
+            f"Remote-target registry capability check failed ({result['failureCode']}).",
+            result,
+        )
 
     credential_state = _parse_access(stdout)
     return {
+        "status": "verified",
+        "executionLocation": "remote-target",
         "targetName": name,
+        "verifiedAddress": address,
+        "credentialContext": (
+            "target-docker-config" if credential_state == "protected" else "target-anonymous"
+        ),
+        "capabilityProved": "registry-manifest-read",
         "image": exact_image,
         "manifestAccess": "verified",
         "credentialConfig": credential_state,
+        "doesNotProve": list(_REMOTE_DOES_NOT_PROVE),
         "mutated": False,
     }
+
+
+def verify_workstation_registry_access(image: str) -> dict[str, Any]:
+    """Verify exact-image manifest access from this workstation without pulling."""
+
+    exact_image = normalize_registry_image(image)
+    command = ["docker", "manifest", "inspect", exact_image]
+    try:
+        completed = subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+        )
+    except FileNotFoundError as error:
+        result = _workstation_failure_result(
+            image=exact_image,
+            failure_code="docker-cli-unavailable",
+        )
+        raise RegistryCapabilityError(
+            "Workstation registry capability check failed (docker-cli-unavailable).",
+            result,
+        ) from error
+
+    if completed.returncode != 0:
+        result = _workstation_failure_result(
+            image=exact_image,
+            failure_code="manifest-access-failed",
+        )
+        raise RegistryCapabilityError(
+            "Workstation registry capability check failed (manifest-access-failed).",
+            result,
+        )
+
+    return {
+        "status": "verified",
+        "executionLocation": "workstation",
+        "credentialContext": "workstation-docker-client",
+        "dockerConfigSource": "explicit-environment" if os.environ.get("DOCKER_CONFIG") else "default",
+        "capabilityProved": "registry-manifest-read",
+        "image": exact_image,
+        "manifestAccess": "verified",
+        "doesNotProve": list(_WORKSTATION_DOES_NOT_PROVE),
+        "mutated": False,
+    }
+
+
+__all__ = [
+    "RegistryCapabilityError",
+    "build_remote_script",
+    "normalize_registry_image",
+    "verify_registry_access",
+    "verify_workstation_registry_access",
+]

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

@@ -1,4 +1,4 @@
-"""CLI for read-only registry access verification."""
+"""CLI for read-only registry capability verification."""
 
 from __future__ import annotations
 
@@ -8,7 +8,11 @@ import sys
 from typing import Any
 
 from .errors import DeploymentKitError
-from .registry_access import verify_registry_access
+from .registry_access import (
+    RegistryCapabilityError,
+    verify_registry_access,
+    verify_workstation_registry_access,
+)
 
 
 def _print(value: Any, *, as_json: bool) -> None:
@@ -28,11 +32,24 @@ def build_parser() -> argparse.ArgumentParser:
 
     verify = sub.add_parser(
         "verify",
-        help="Verify exact-image registry manifest access without pulling or modifying target state",
+        help=(
+            "Verify exact-image registry manifest access on the named remote target without pulling "
+            "or modifying target state"
+        ),
     )
-    verify.add_argument("name")
+    verify.add_argument("name", help="Named remote target profile")
     verify.add_argument("--image", required=True)
     verify.add_argument("--json", action="store_true")
+
+    verify_workstation = sub.add_parser(
+        "verify-workstation",
+        help=(
+            "Verify exact-image registry manifest access from this workstation without pulling "
+            "or modifying target state"
+        ),
+    )
+    verify_workstation.add_argument("--image", required=True)
+    verify_workstation.add_argument("--json", action="store_true")
     return parser
 
 
@@ -45,6 +62,18 @@ def main(argv: list[str] | None = None) -> int:
                 as_json=args.json,
             )
             return 0
+        if args.command == "verify-workstation":
+            _print(
+                verify_workstation_registry_access(args.image),
+                as_json=args.json,
+            )
+            return 0
+    except RegistryCapabilityError as error:
+        if getattr(args, "json", False):
+            _print(error.result, as_json=True)
+        else:
+            print(f"ERROR: {error}", file=sys.stderr)
+        return 2
     except DeploymentKitError as error:
         print(f"ERROR: {error}", file=sys.stderr)
         return 2

package/package.json

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

package/src/cli.mjs

@@ -44,6 +44,11 @@ function inferConsumer(root) {
   return path.basename(root);
 }
 
+export function componentRevisionForDisplay(component) {
+  const revision = component?.revision ?? component?.commit;
+  return typeof revision === 'string' && revision ? revision : '<unknown revision>';
+}
+
 function printPlan(plan, bootstrapMigrations = { rows: [], unsafe: [] }) {
   console.log(`Project Forge profile: ${plan.profileName}`);
   if (bootstrapMigrations.rows.length) {
@@ -51,7 +56,7 @@ function printPlan(plan, bootstrapMigrations = { rows: [], unsafe: [] }) {
     for (const row of bootstrapMigrations.rows) console.log(`${row.state.padEnd(30)} ${row.path}`);
   }
   for (const component of plan.plans) {
-    console.log(`\n${component.componentId.toUpperCase()} ${component.component.commit}`);
+    console.log(`\n${component.componentId.toUpperCase()} ${componentRevisionForDisplay(component.component)}`);
     for (const row of component.rows) console.log(`${row.state.padEnd(20)} ${row.path}`);
     for (const retired of component.retired) console.log(`${retired.state.padEnd(20)} ${retired.path}`);
   }
@@ -112,7 +117,7 @@ export async function run(argv = process.argv.slice(2), packageData = loadPackag
     console.log(`Available package: ${packageData.pkg.name}@${packageData.pkg.version}`);
     console.log(`Profile: ${installed.profile}`);
     for (const [name, component] of Object.entries(installed.components ?? {})) {
-      console.log(`${name}: ${component.version ? component.version + ' @ ' : ''}${component.commit}`);
+      console.log(`${name}: ${component.version ? component.version + ' @ ' : ''}${componentRevisionForDisplay(component)}`);
     }
     return 0;
   }