@mriekki/project-forge 4.6.0 → 4.8.0

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/core/core/skills/setup/SKILL.md

@@ -65,6 +65,14 @@ Do not require another workstation to be online and do not treat another compute
 
 Detect the current OS automatically. Do not ask the developer which setup launcher to use when the platform can be observed.
 
+If the observed workstation OS is not declared in mutable `DEV_ENVIRONMENT.json`, surface that explicitly before claiming setup support:
+
+```text
+NEW WORKSTATION — PLATFORM NOT DECLARED
+```
+
+Do not silently reinterpret Bootstrap provenance or append a platform merely because tools happen to run. If current repository/catalog evidence supports the stack on the observed OS, offer one reviewed **consumer-owned** platform expansion to `DEV_ENVIRONMENT.json`; otherwise report the concrete unsupported/capability gap. Preserve original `PROJECT_BOOTSTRAP.json` provenance.
+
 A workspace instance owns machine-local state such as local runtime/data, SSH private keys/trust, credential-manager entries, Docker state, and repository-scoped readiness evidence. Git/GitHub is the shared source-code coordination boundary. Never invent a central workstation registry merely to coordinate another computer.
 
 ## 2. `status` is read-only
@@ -112,6 +120,10 @@ setup --check
 
 A manually invoked `/setup` authorizes routine, bounded, non-destructive local setup that the generated script already owns: supported tool installation, VS Code extension installation, dependency restore, personal Project Forge profile initialization, and other declared workstation preparation.
 
+Before a large workstation install run, surface all currently knowable prerequisites together when the generated tooling exposes them: missing tools, runtime/version pins, editor extensions, Docker operational state, interactive elevation/terminal requirements, and durable fresh-shell discovery. Group unavoidable sudo/administrator or secret-bearing prompts into clear terminal handoffs instead of discovering them one installer at a time.
+
+A temporary process `PATH` adjustment may prove a diagnosis but does not by itself prove durable tool discovery. Re-check important runtime commands in the environment a fresh terminal/editor will use before reporting final readiness.
+
 Stop before destructive replacement, unrelated machine mutation, secret disclosure, or repair outside the declared setup contract.
 
 ## 4. `/setup local` converges verified local development readiness
@@ -132,7 +144,7 @@ When application source/runtime exists, converge only the repository-owned local
 
 Verify supported tools/versions using repository setup/doctor tooling when present. Run repository-defined dependency restore/setup commands when missing or stale. Preserve pinned versions and project conventions.
 
-Treat **installation**, **version compatibility**, and **operational readiness** as separate evidence when tooling exposes those distinctions. A successful CLI/version probe does not prove that the backing service/runtime is operational. For Docker-based setup, do not call the runtime ready merely because `docker --version` succeeds; require the repository/doctor operational probe before relying on Docker Engine capability.
+Treat **installation**, **version compatibility**, and **operational readiness** as separate evidence when tooling exposes those distinctions. A successful CLI/version probe does not prove that the backing service/runtime is operational for the required Project Forge action. For Docker-based setup, do not call the runtime ready merely because `docker --version` succeeds; require the repository/doctor operational probe before relying on Docker Engine capability.
 
 ### B. Local persistence
 
@@ -266,6 +278,26 @@ For remote SSH preserve strict host identity. Unknown/changed host identity is a
 
 Remote readiness does not require configuring Production when the selected environment is non-Production. Production classification remains project topology/policy, not a literal-name check.
 
+### One read-only remote preflight before recovery
+
+Before asking the developer to repair one SSH prerequisite at a time, collect all currently knowable target-access facts through supported deterministic status/diagnosis surfaces. When installed Deployment Kit exposes the access diagnosis command, prefer:
+
+```text
+project-forge-deploy access diagnose <target> --json
+```
+
+If stable name resolution is unavailable and the developer supplies an exact address independently observed at the trusted target console, carry that address through read-only diagnosis without persisting it:
+
+```text
+project-forge-deploy access diagnose <target> --address <exact-ip> --json
+```
+
+The exact IP is address-path evidence, not a replacement SSH identity. Preserve the configured `HostKeyAlias`, target-specific trust, and configured identity. Do not store the address merely because it made diagnosis possible. Persist it only through the separately gated verified-address operation after strict SSH succeeds.
+
+When diagnosis exposes route-source evidence, use the actual selected local source address/interface for any source-policy discussion. Never assume Wi-Fi, Ethernet, the first interface, or a subnet merely from workstation configuration.
+
+If the Deployment Kit version does not expose the supported diagnosis surface, use its documented structured environment status/plan commands. Do not substitute ad hoc Python imports or unbounded raw `ssh -vvv` transcripts as normal orchestration.
+
 ### Guided remote failure recovery is part of `/setup`
 
 A supported deterministic setup/readiness failure is not, by itself, the end of `/setup`. When installed Deployment Kit tooling returns structured diagnosis or a bounded next action, continue through that diagnosis automatically until one of these boundaries is reached:
@@ -278,7 +310,7 @@ A supported deterministic setup/readiness failure is not, by itself, the end of
 
 Do **not** merely repeat an opaque subprocess exit code and tell the developer to fix access independently when deterministic diagnosis is available.
 
-For SSH target-access failure, prefer the Deployment Kit's structured environment setup status/plan evidence. Preserve distinct categories such as:
+Preserve distinct categories such as:
 
 ```text
 name resolution / address path
@@ -293,8 +325,45 @@ remote account/source-policy rejection
 
 Keep credentials, private keys, raw secure-prompt content, and unbounded SSH transcripts out of conversational diagnostics and journals.
 
+For fingerprint input, show the expected public form such as `SHA256:<fingerprint>` and validate that shape before progressing. Distinguish the **server host fingerprint**, the **client public-key fingerprint**, and passwords/passphrases. If input looks credential-like rather than fingerprint-shaped, do not repeat it into commands, reports, journals, or upstream issues.
+
+If a local key/agent operation requires a passphrase or another terminal-owned secret prompt, follow the interactive-terminal handoff contract: collect any distinct bounded authorization once, then immediately provide the exact standalone copyable command, correct machine/working directory, expected local prompt, and the non-secret completion evidence to report. Do not ask for the passphrase through chat or ask a second ceremonial question merely to repeat the same authorized command.
+
 If client-side evidence shows that the configured key reached the server but access is still rejected, stop reinstalling the same key. Route to a trusted target console or already-authorized administrative session to inspect effective account/source policy. Do not guess that `AllowUsers`, `AllowGroups`, PAM, or another server rule is the exact cause until server-side evidence establishes it.
 
+### One bounded trusted-console diagnostic bundle
+
+When client evidence reaches the server but cannot establish why the account/session is rejected, request one compact server-side evidence bundle instead of a chain of one-fact-at-a-time questions. Limit the bundle to the facts needed for the selected account and actual route-selected source:
+
+- intended SSH account;
+- whether the expected **client public-key fingerprint** is present for that account, without dumping unrelated authorized keys;
+- ownership/modes for the account's `.ssh` directory and `authorized_keys`;
+- a narrowly scoped recent authentication reason for the attempted source/account;
+- effective SSH allow/deny policy relevant to that account and source;
+- the file/include/`Match` location that owns any relevant directive.
+
+State exactly where to run each console command and what non-secret output to return. Never request full SSH configs/logs, passwords, private keys, tokens, or unrelated authorized-key material when the focused bundle is enough.
+
+Client evidence may classify `remote-authentication-rejected` or `remote-account-policy-rejected`, but only trusted server-side evidence may establish a concrete cause such as `AllowUsers`.
+
+### One exact server-policy repair after evidence
+
+If the trusted-console evidence establishes that a server-side account/source policy change is required, prepare **one exact repair plan** before any write. The plan must show:
+
+- exact affected file/directive and relevant before/after state;
+- the actual durable source address/interface assumption being authorized;
+- preservation of existing allow/deny entries unless the operator explicitly chooses otherwise;
+- an exact backup of the affected file before editing;
+- syntax/config validation before reload;
+- preservation of the current trusted administrative session until new strict access is proven;
+- reload/restart scope, rollback command, and explicit stop conditions.
+
+Do not present configuration text as if it were a shell command. Give either one copyable bounded command or explicit editor instructions on the **target host**, with the file path stated. Do not assume that adding a new drop-in overrides or composes safely with existing includes/`Match` blocks. Never broaden a specific source restriction to a subnet merely for convenience.
+
+A server-policy write remains a distinct operator/administrative authorization. Once the exact reviewed repair is authorized and the human reports it completed, do not ask the same authorization again: automatically re-run strict structured diagnosis/verification, then continue through separately gated address persistence, host-platform readiness, and proof as applicable.
+
+If the human says stop, done, or pause at any point, stop modifying state. Read-only reporting may summarize what is already known, but newly observed prerequisite changes do not override the expressed pause.
+
 ### Gate password-assisted bootstrap on server capability
 
 Before recommending a password-assisted/Home Lab bootstrap against a reachable server, use deterministic evidence of the server-advertised authentication methods when the installed Deployment Kit supports that probe.
@@ -355,6 +424,8 @@ For a Production-class environment, keep the proof explicitly labeled as a **PRO
 
 If cleanup fails, report `PROOF PASSED — CLEANUP ACTION NEEDED`; do not claim a clean setup.
 
+When proof output distinguishes `transferState: transferred` from `transferState: already-present`, report that distinction. A proof that reused an exact cached image may still prove runtime/health/cleanup, but it must not be described as an observed fresh workstation-to-target image transfer. If fresh transport itself must be tested, plan that separately without deleting or pruning a shared image cache merely to manufacture evidence.
+
 When installed Deployment Kit provides a durable local proof receipt or equivalent discoverable evidence, record/reuse it rather than relying on chat history. Reuse only while its target binding, host identity, workstation identity, adapter/provenance, logical environment, and cleanup result remain applicable. A new chat alone must not invalidate valid machine evidence.
 
 ## 9. `repair` is bounded and fail-closed
@@ -382,9 +453,27 @@ Stop for a separate explicit decision before:
 
 ## 11. Completion and handoff
 
-After setup, report evidence rather than inferring human acceptance.
+After setup, report evidence rather than inferring human acceptance. Keep independent readiness dimensions independent instead of collapsing them into one `READY` label.
+
+Prefer a compact final shape such as:
+
+```text
+SETUP RESULT
+
+Local tools/runtime ......... VERIFIED / BLOCKED / NOT APPLICABLE
+Fresh-shell discovery ....... VERIFIED / CAVEAT / BLOCKED
+Build/tests ................. VERIFIED / BLOCKED / NOT RUN
+Remote target access ........ VERIFIED / BLOCKED / NOT CONFIGURED
+Host platform ............... READY / BLOCKED / NOT APPLICABLE
+Deployment path ............. PROVEN / NOT PROVEN / BLOCKED
+Proof image transfer ........ TRANSFERRED / CACHE REUSED / NOT RUN
+Proof cleanup ............... CLEAN / ACTION NEEDED / NOT RUN
+Project application ......... NOT DEPLOYED / <actual evidence>
+Repository CI ............... PASS / BLOCKED / NOT CHECKED
+Human workspace acceptance .. CONFIRMED / PENDING
+```
 
-A generated setup/doctor/proof success is machine evidence. Human workspace acceptance remains distinct.
+A generated setup/doctor/proof success is machine evidence. Human workspace acceptance remains distinct. A continuation/override for a documented Project Forge defect is not a CI waiver and is not human workspace acceptance; preserve its exact scope so resuming setup does not repeatedly ask the same decision.
 
 Useful next actions include:
 - `/next-step` — one sensible next action after current evidence is known;
@@ -393,4 +482,4 @@ Useful next actions include:
 - `/deploy <environment>` — only after readiness and its own authorization contract;
 - `/tear-down <scope>` — destructive cleanup under its separate gate.
 
-Do not create a second top-level developer-environment-mode workflow. Local/remote workstation convergence belongs here.
+Do not create a second top-level developer-environment-mode workflow. Local/remote workstation convergence belongs here.

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

@@ -0,0 +1,65 @@
+"""CLI for strict target-access diagnosis."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from .access_diagnosis import diagnose_target_access
+from .errors import DeploymentKitError
+
+
+def _print(value: Any, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(value, indent=2, sort_keys=True))
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if isinstance(item, (dict, list)):
+                print(f"{key}: {json.dumps(item, sort_keys=True)}")
+            else:
+                print(f"{key}: {item}")
+        return
+    print(value)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="project-forge-deploy access",
+        description="Read-only strict SSH target-access diagnosis.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    diagnose = subparsers.add_parser(
+        "diagnose",
+        help="Diagnose one configured target without mutating target or workstation state",
+    )
+    diagnose.add_argument("name")
+    diagnose.add_argument(
+        "--address",
+        help=(
+            "Exact temporary IPv4/IPv6 address independently confirmed by the operator. "
+            "Used only for this read-only diagnosis and never persisted."
+        ),
+    )
+    diagnose.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "diagnose":
+            result = diagnose_target_access(args.name, temporary_address=args.address)
+            _print(result, as_json=args.json)
+            return 0 if result.get("state") == "verified" else 2
+        raise DeploymentKitError("Unsupported access command.")
+    except DeploymentKitError as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,116 @@
+"""Read-only strict target-access diagnosis with optional temporary address evidence."""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+import re
+import shutil
+import socket
+import subprocess
+import sys
+from typing import Any
+
+from .errors import DeploymentKitError
+from .profiles import load_profile
+from .ssh import diagnose_access
+
+
+def _temporary_address(value: str | None) -> str | None:
+    if value is None:
+        return None
+    try:
+        parsed = ipaddress.ip_address(value)
+    except ValueError as error:
+        raise DeploymentKitError("Temporary target address must be an exact IPv4 or IPv6 address.") from error
+    if isinstance(parsed, ipaddress.IPv6Address) and parsed.scope_id is not None:
+        raise DeploymentKitError("Temporary target address must not include an IPv6 scope identifier.")
+    return str(parsed)
+
+
+def _route_interface(address: str) -> str | None:
+    if sys.platform == "darwin":
+        route = shutil.which("route") or ("/sbin/route" if os.path.exists("/sbin/route") else None)
+        if route:
+            result = subprocess.run(
+                [route, "-n", "get", address],
+                check=False,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            if result.returncode == 0:
+                match = re.search(r"^\s*interface:\s*(\S+)\s*$", result.stdout, re.MULTILINE)
+                if match:
+                    return match.group(1)
+    elif os.name != "nt":
+        ip = shutil.which("ip")
+        if ip:
+            result = subprocess.run(
+                [ip, "route", "get", address],
+                check=False,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            if result.returncode == 0:
+                match = re.search(r"\bdev\s+(\S+)", result.stdout)
+                if match:
+                    return match.group(1)
+    return None
+
+
+def route_source_evidence(address: str, port: int) -> dict[str, Any]:
+    """Return the local route-selected source for one exact target address without scanning."""
+    parsed = ipaddress.ip_address(address)
+    family = socket.AF_INET6 if isinstance(parsed, ipaddress.IPv6Address) else socket.AF_INET
+    evidence: dict[str, Any] = {
+        "targetAddress": str(parsed),
+        "targetPort": int(port),
+        "sourceAddress": None,
+        "interface": _route_interface(str(parsed)),
+    }
+    try:
+        with socket.socket(family, socket.SOCK_DGRAM) as probe:
+            probe.connect((str(parsed), int(port)))
+            evidence["sourceAddress"] = probe.getsockname()[0]
+    except OSError as error:
+        evidence["sourceProbeError"] = str(error)
+    return evidence
+
+
+def diagnose_target_access(name: str, *, temporary_address: str | None = None) -> dict[str, Any]:
+    """Diagnose strict SSH access without persisting a temporary address override."""
+    profile = load_profile(name)
+    address = _temporary_address(temporary_address)
+    effective = dict(profile)
+    if address is not None:
+        effective["addressOverride"] = address
+
+    diagnosis = diagnose_access(effective)
+    used_address = diagnosis.get("address")
+    if used_address is None and address is not None:
+        used_address = address
+
+    result: dict[str, Any] = {
+        **diagnosis,
+        "addressInput": (
+            {
+                "source": "temporary-operator-confirmed",
+                "address": address,
+                "persisted": False,
+            }
+            if address is not None
+            else {
+                "source": "profile",
+                "address": profile.get("addressOverride"),
+                "persisted": profile.get("addressOverride") is not None,
+            }
+        ),
+        "mutated": False,
+    }
+    if used_address is not None:
+        result["routeSource"] = route_source_evidence(used_address, int(profile["port"]))
+    return result

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,