prizmkit 1.1.171 → 1.1.174

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  {
2
- "frameworkVersion": "1.1.171",
3
- "bundledAt": "2026-08-06T15:22:17.562Z",
4
- "bundledFrom": "c90abca"
2
+ "frameworkVersion": "1.1.174",
3
+ "bundledAt": "2026-08-08T02:37:10.579Z",
4
+ "bundledFrom": "b12b5d8"
5
5
  }
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.1.171",
2
+ "version": "1.1.174",
3
3
  "skills": {
4
4
  "prizmkit": {
5
5
  "description": "Framework introduction and navigation for the formal single-requirement lifecycle, project initialization, Prizm docs, and independent deployment.",
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: "prizmkit-deploy"
3
- description: "Deploy the latest allowed release to local, remote, test, production, or custom targets through an intent-first one-click Profile convergence loop, and handle status, health, logs, restart, rollback, takeover, and resume. Use this skill whenever the user asks to deploy, redeploy, ship quickly or without confirmation, publish a release, inspect or recover a deployment, promote an artifact, configure post-deploy CI/CD, or replace repeated local deployment with watch/hot reload. Explicit deploy invocation authorizes ordinary project-owned deployment actions; collect only indispensable missing information and continue through verification to a terminal result. Respect explicit no-confirmation and no-backup intent for the selected operation; unresolved identity, target, unbounded effects, and shared or unknown ownership remain real information boundaries. (project)"
3
+ description: "Deploy and operate the current project through an intent-first, evidence-driven fast path with verification, bounded repair, rollback, and recovery. Use whenever the user asks to deploy, redeploy, ship, or publish an app, site, or API; deploy to a server, SSH host, cloud hosting platform, container/Docker target, or test/staging/production environment; inspect status, health, or logs; restart, rollback, resume, or take over a deployment; configure post-deploy CI/CD; or set up local watch/hot reload. Explicit deployment authorizes bounded project-owned actions, so ask only for unresolved release source, target, user-only authentication, irreversible or unbounded data effects, or shared/unknown ownership. Respect no-confirmation and no-backup intent. (project)"
4
4
  ---
5
5
 
6
- # PrizmKit Deploy — C-Lite AutoDeploy Gateway
6
+ # PrizmKit Deploy — Intent-First Fast-Path Gateway
7
7
 
8
8
  `/prizmkit-deploy` deploys and operates the current project through semantic capabilities proven from current project, target, tool, and official evidence. Product, provider, controller, language, framework, tool, and operating-system names are evidence, not protocol routes.
9
9
 
@@ -18,30 +18,39 @@ Use this Skill for:
18
18
  - deployment validation, diagnostics, interrupted-operation resume, and decommission/forget intent;
19
19
  - optional post-success remote CI/CD or local continuous-development setup.
20
20
 
21
- Do not use it for unrelated application implementation, general server administration, or resources outside the selected Profile and its necessary deployment dependencies. If the user says only “ship it” without explicitly invoking this Skill, clarify commit versus deploy; explicit invocation means deploy.
21
+ Do not use it for unrelated application implementation, general server administration, or resources outside the selected environment and its necessary deployment dependencies. If the user says only “ship it” without explicitly invoking this Skill, clarify commit versus deploy; explicit invocation means deploy.
22
+
23
+ Deployment verification is Release-and-target convergence, not a generic software-development lifecycle. A caller cannot add hidden planning, review, commit, or exhaustive unit/integration/contract/browser test prerequisites. Run only checks required by the selected project-native deployment/preflight controller or by target-appropriate deployment verification, unless the user separately requests broader development work. A selected immutable worktree Release does not require creating a Git commit.
22
24
 
23
25
  ## Invocation and Authority
24
26
 
25
27
  ```text
26
- /prizmkit-deploy → deploy the selected/default Profile
27
- /prizmkit-deploy <profile> → deploy that Profile
28
- /prizmkit-deploy plan → discover and preview without writes
28
+ /prizmkit-deploy → deploy the project default environment
29
+ /prizmkit-deploy <environment> → deploy the named environment
30
+ /prizmkit-deploy plan → discover and preview without writes
29
31
  ```
30
32
 
31
- Explicit deploy invocation authorizes the standard deployment envelope: project reads, build/package, project-declared dependency resolution, non-destructive native migration, candidate creation, start/restart, live handoff, minimum verification, bounded retry, exact old-release retirement, failed-candidate/temporary-resource cleanup, and the selected Profile record update.
33
+ An existing Profile ID remains a compatible internal locator, but ordinary interaction uses environment names. Default to one deployable unit. Enable multiple units only when project-native configuration proves independent targets or lifecycles. When multiple environments exist, use the configured default environment; ask one target question only when no default exists and current evidence cannot identify one environment unambiguously.
34
+
35
+ Explicit deploy invocation authorizes the standard deployment envelope: project reads, build/package, project-declared dependency resolution, non-destructive native migration, candidate creation, start/restart, live handoff, minimum verification, bounded retry, exact old-release retirement, failed-candidate/temporary-resource cleanup, and the selected environment's internal Profile record update.
36
+
37
+ User intent controls optional confirmation and backup policy for the selected operation. For quick deployment, no-confirmation intent, or equivalent wording, collect only information indispensable to identify the target, authenticate, choose the release source, bind the release, or resolve an otherwise unknowable effect. Continue bounded discovery, execution, repair, recovery, and verification until a terminal outcome. Keep progress updates concise and non-blocking, then notify the user of the final verified result.
32
38
 
33
- User intent controls optional confirmation and backup policy for the selected operation. For quick deployment, no-confirmation intent, or equivalent wording, collect only information indispensable to identify the target, authenticate, bind the release, or resolve an otherwise unknowable effect. Continue bounded discovery, execution, repair, recovery, and verification until a terminal outcome. Keep progress updates concise and non-blocking, then notify the user of the final verified result.
39
+ An explicit no-confirmation instruction satisfies any confirmation or effect decision already identified within the user's established authority; do not ask again. An explicit no-backup instruction creates no new data backup, snapshot, or retained application rollback copy for this operation. Preserve current live only until the desired candidate is proven, then retire exact superseded runtime after handoff. Leave unrelated pre-existing backups untouched unless the user explicitly requests their deletion. These instructions do not invent missing facts, choose whether uncommitted code is deployed, make unknown effects bounded, bypass target identity, or establish ownership the user has not demonstrated.
34
40
 
35
- An explicit no-confirmation instruction satisfies any confirmation or effect decision already identified within the user's established authority; do not ask again. An explicit no-backup instruction creates no new data backup, snapshot, or retained application rollback copy for this operation. Preserve current live only until the desired candidate is proven, then retire exact superseded runtime after handoff. Leave unrelated pre-existing backups untouched unless the user explicitly requests their deletion. These instructions do not invent missing facts, make unknown effects bounded, bypass target identity, or establish ownership the user has not demonstrated.
41
+ Explicit permission to use local SSH credentials authorizes target-scoped use of configured SSH aliases, agent identities, and key files through the installed `ssh` executable. Do not ask whether to use them again. Let SSH consume the credential; do not read, copy, print, upload, or request the private-key value. This permission does not identify a missing destination, accept an unverified or changed host key, or authorize unrelated hosts.
36
42
 
37
43
  Do not ask for a second complete-plan confirmation for standard actions. Before returning `WAITING_USER`, exhaust bounded read-only discovery, unambiguous target resolution, configured non-interactive authentication, and every safe bounded forward action. Pause only when no safe automatic continuation remains and the next action requires:
38
44
 
39
- 1. an identity or authentication action only the user can complete after established credentials have been tried;
40
- 2. a target choice that remains absent, conflicting, or ambiguous after current evidence is inspected;
41
- 3. an irreversible data effect not already accepted for this exact target and action, or a data effect that remains insufficiently bounded;
42
- 4. a shared or unknown-ownership resource decision not already resolved within the user's established authority.
45
+ 1. a release-source choice because tracked or untracked worktree changes exist;
46
+ 2. an identity or authentication action only the user can complete after established credentials have been tried;
47
+ 3. a target choice that remains absent, conflicting, or ambiguous after current evidence is inspected;
48
+ 4. an irreversible data effect not already accepted for this exact target and action, or a data effect that remains insufficiently bounded;
49
+ 5. a shared or unknown-ownership resource decision not already resolved within the user's established authority.
43
50
 
44
- A missing Profile record, ordinary first deployment, selected-target SSH connection, known bounded downtime, material work inside the standard envelope, or missing rollback mechanism does not create a confirmation. Disclose relevant effects while continuing. Privileged or global work outside the Profile's already established target boundary is an authorization/ownership decision and pauses before execution.
51
+ A missing Profile record, ordinary first deployment, selected-target connection, known bounded downtime, material work inside the standard envelope, or missing rollback mechanism does not create a confirmation. Disclose relevant effects while continuing. Privileged or global work outside the selected environment's established target boundary is an authorization/ownership decision and pauses before execution.
52
+
53
+ When SSH still cannot connect after bounded target-scoped discovery and use of authorized local credentials, diagnose the observed failure class before pausing. Report why connection failed, which non-sensitive binding was attempted, and exactly which destination, username, port, proxy/VPN, trusted host-key fingerprint, public-key registration, network rule, SSH service, or remote permission fact must change for future automatic access. Return one connection-enablement action, then retry and perform the server work yourself. Never ask the user to log into the server and run deployment commands on this Skill's behalf.
45
54
 
46
55
  ## Managed Artifacts
47
56
 
@@ -52,47 +61,57 @@ Prefer project-native deployment configuration. PrizmKit owns only:
52
61
  | `prizmkit.deploy.json` | Optional version-controlled non-sensitive declaration index for Profile hints and policy |
53
62
  | `.prizmkit/deploy/profiles/<profile-id>.json` | One local non-sensitive current/result/recovery record per stable Profile |
54
63
 
55
- A missing Profile record means only that PrizmKit has not recorded this location. Resolve a provisional target from the explicit request, valid declaration and referenced native configuration, or one unambiguous project-native/SSH target, then inspect it directly and derive the stable lowercase Profile ID. Do not pause merely because the record is absent or the target came from a valid declared default. Ask one target question only when no location resolves, multiple candidates remain, or target evidence conflicts. Absence never proves the target is empty; adopt observed current state instead of creating a duplicate deployment.
64
+ A missing Profile record means only that PrizmKit has not recorded this location. Resolve a provisional target from the explicit request, valid declaration and referenced native configuration, or one unambiguous project-native target. Inspect the target directly and derive the stable lowercase Profile ID after resolution. Do not pause merely because the record is absent or the target came from a valid declared default. Ask one target question only when no location resolves, multiple candidates remain, or target evidence conflicts. Absence never proves the target is empty; adopt observed current state instead of creating a duplicate deployment.
65
+
66
+ Keep actual IP addresses, URLs, credentials, and dynamic endpoints out of Profile IDs and filenames. Use non-sensitive target references and fingerprints inside managed objects. File count grows only with declared environments, never with deployments, releases, phases, capabilities, history entries, or recovery events.
56
67
 
57
- Keep actual IP addresses, URLs, credentials, and dynamic endpoints out of Profile IDs and filenames. Use non-sensitive target references and fingerprints inside the managed objects. File count grows only with declared Profiles, never with deployments, releases, phases, capabilities, history entries, or recovery events.
68
+ Validate either managed artifact through one read-only entry point: `python3 ${SKILL_DIR}/scripts/validate-deploy-artifact.py --kind <declaration|record> <path>`.
58
69
 
59
- Validate either managed artifact through one read-only entry point: `python3 ${SKILL_DIR}/scripts/validate-deploy-artifact.py --kind <declaration|record> <path>`. It loads the matching shipped JSON Schema, applies structural and semantic checks, and for a Profile record requires `<path>` to end in `<profile.id>.json`. Use managed fields only when this command passes. On failure preserve the rejected candidate and actual target state; never replay or roll back deployment work merely to repair a record. Profile record writes are part of the standard deploy envelope; modifying the optional version-controlled declaration remains an explicit project-file request.
70
+ The validator loads the matching shipped JSON Schema, applies structural and semantic checks, and for a Profile record requires `<path>` to end in `<profile.id>.json`. Use managed fields only when validation passes. On failure, preserve the rejected candidate and actual target state; never replay or roll back deployment work merely to repair a record. Profile record writes are part of the standard deploy envelope. Modifying the optional version-controlled declaration remains an explicit project-file request.
60
71
 
61
72
  When legacy `.prizmkit/deploy/` evidence exists, read `${SKILL_DIR}/references/legacy-migration.md`. Preserve uncertain evidence and stop legacy writers.
62
73
 
63
74
  Secret values stay in user- or target-owned Secret systems. Managed artifacts contain only names, external source references, and presence states. Never persist raw command output or full logs.
64
75
 
65
- ## Remote Connection Default
76
+ ## Deployment Unit, Environment, and Fast Path
66
77
 
67
- For a Profile whose selected target is a directly managed remote machine, use the installed `ssh` command as the default transport for discovery, deployment, operations, and verification. SSH implements the semantic `connect` capability; it is not a Profile type or a provider/tool route. Prefer an observed or user-supplied SSH config alias and reuse its user, port, proxy, agent/key, and host-verification settings. Run bounded non-interactive remote commands instead of opening an unmanaged interactive shell when the action permits it.
78
+ Default to one deployable unit and resolve its environment from the explicit request, the valid declared default, one project-native default, or one unambiguous observed target.
68
79
 
69
- For a resolved remote destination, attempt one bounded non-interactive SSH probe with the established config, agent/key, proxy, and host-key evidence before asking about authentication. A successful probe continues directly into observation and deployment. Do not ask the user to confirm credentials that already work. If the destination is still incomplete, ask one target question for the config alias or destination and any non-default port; do not guess the host, user, port, private-key path, or bastion. Connecting to the selected target is part of explicit deploy authority. Pause only when the probe proves a user-only authentication action is required or target identity cannot be established. Preserve host-key verification, and treat an unknown or changed key without trusted fingerprint evidence as an identity decision rather than bypassing the check.
80
+ Read `${SKILL_DIR}/references/fast-path-selection.md` after resolving the operation and candidate environment. Select the smallest controller supported by current evidence, then load only the matching playbook:
70
81
 
71
- This default does not override stronger current evidence. Use the project-native target/control-plane path when the target is local, exposes no host shell, or declares a different authoritative deployment transport. A transfer action may use an available SSH-backed transfer executable while preserving the same verified destination and authentication boundary.
82
+ - project-native command or controller → `${SKILL_DIR}/references/playbook-project-native.md`
83
+ - repository-hosted deployment → `${SKILL_DIR}/references/playbook-repository-hosted.md`
84
+ - image or multi-service container deployment → `${SKILL_DIR}/references/playbook-container.md`
85
+ - direct remote machine, process supervisor, or reverse-proxy handoff → `${SKILL_DIR}/references/playbook-remote-runtime.md`
86
+ - no specialized match → `${SKILL_DIR}/references/playbook-generic-fallback.md`
87
+
88
+ Products and tools are evidence examples, not protocol identifiers. Existing project-native coordination decides whether multiple units deploy together or independently.
89
+
90
+ A cloud server, virtual machine, or directly managed host remains a direct remote-runtime target when project evidence establishes shell access. On that path, use the installed `ssh` executable as the default connection transport. A provider dashboard does not reclassify the machine as repository-hosted deployment. Do not use browser automation or a web terminal as a substitute for SSH to transfer a Release, execute deployment commands, or inspect runtime state. Browser automation is eligible only for an exact authoritative control-plane operation when no project-native command, API, CLI, or SSH path can perform that operation; it never bypasses identity or authentication boundaries.
72
91
 
73
92
  ## AutoDeploy Workflow
74
93
 
75
- ### 1. Select Profile
94
+ ### 1. Resolve Unit and Environment
76
95
 
77
- 1. Resolve a candidate from the explicitly requested Profile, a valid declared default, the sole known Profile, or one unambiguous project-native deployment target.
78
- 2. If that candidate has no Profile record but its location resolves from the request, valid declaration/native configuration, or one matching SSH target, inspect it directly and derive the stable Profile identity without confirmation.
79
- 3. If no named candidate exists but current evidence identifies exactly one target, adopt it provisionally and inspect it before writing a Profile record.
80
- 4. Ask one target question only when no target resolves, multiple candidates remain, or evidence conflicts; never ask merely because this is the first deployment.
96
+ 1. Treat the project as one deployable unit unless project-native evidence proves multiple independent units.
97
+ 2. Resolve the explicit or configured default environment automatically.
98
+ 3. Inspect one unambiguous target before creating an internal Profile record.
99
+ 4. Ask one environment/target action only when no unique target resolves.
81
100
 
82
- Different Profiles may operate independently. When the same Profile already has recoverable work, attach to or resume it instead of creating a second candidate.
101
+ Profile records remain internal state caches. Existing unified deployment controllers preserve their coordination boundary; otherwise independent units remain independent. When the same environment already has recoverable work, attach to or resume it instead of creating a second candidate.
83
102
 
84
- ### 2. Observe Current
103
+ ### 2. Observe Current and Select a Fast Path
85
104
 
86
105
  Read only the project-native files and target observations needed to establish:
87
106
 
88
- - current source/release and the Profile's latest allowed release;
107
+ - current source/release and the environment policy's latest allowed release;
89
108
  - actual target identity, authorization, live selector, runtime units, and configured health;
90
109
  - exact project-owned candidates, rollback releases, superseded units, failed attempts, temporary resources, and orphans;
91
110
  - persistent/shared dependencies that must not be retired;
92
111
  - project-native reports or immutable artifacts that can be reused;
93
112
  - selected commands and material child effects through an executable, target-native, or human boundary.
94
113
 
95
- Resolve the connection path through the Remote Connection Default before deriving remote actions. Current target and project-native control-plane evidence outrank the local Profile summary. Reconcile drift from observed state. Do not expose Secret values or substitute conventional ports/endpoints for observed configuration.
114
+ Use `fast-path-selection.md` to select one evidence-backed controller and load only the implicated playbook. Current target and project-native control-plane evidence outrank the local Profile summary. Reconcile drift from observed state. Do not expose Secret values or substitute conventional ports/endpoints for observed configuration.
96
115
 
97
116
  Read `${SKILL_DIR}/references/capability-contract.md` when selecting or deriving an action.
98
117
 
@@ -100,9 +119,10 @@ Read `${SKILL_DIR}/references/capability-contract.md` when selecting or deriving
100
119
 
101
120
  Fix one desired release for the operation:
102
121
 
103
- 1. use the Profile policy's latest eligible immutable project artifact when available;
104
- 2. otherwise use the current committed revision;
105
- 3. do not silently include uncommitted workspace content as a release.
122
+ 1. use the environment policy's latest eligible immutable project artifact when available;
123
+ 2. otherwise, when the worktree is clean, use the current committed revision;
124
+ 3. when the worktree is dirty, return one `WAITING_USER` release-source action with mutually exclusive choices: current worktree, current commit, or stop;
125
+ 4. when current worktree is selected, create a bounded immutable build input with a content identity, exclude ignored files and Secrets, and do not create a Git commit.
106
126
 
107
127
  Keep the desired release fixed through retries and recovery. When current and desired are the same release and required minimum health passes, report the same release as converged and run no material build, package, release, or restart.
108
128
 
@@ -113,12 +133,14 @@ Read `${SKILL_DIR}/references/policy-and-execution.md` before a write or materia
113
133
  1. compute the current → desired difference;
114
134
  2. choose the smallest evidence-supported next action;
115
135
  3. activate only the conditional Gates implicated by that action;
116
- 4. execute within a finite resource/retry boundary;
136
+ 4. execute once, then allow at most two evidence-supported repair rounds for that failing step;
117
137
  5. observe the result before selecting another action.
118
138
 
139
+ Each repair round starts from fresh target observations. Do not repeat the same action after the same failure unless new evidence changes its preconditions or executable shape.
140
+
119
141
  For redeploy, preserve the proven old live release until the candidate passes its handoff boundary. After handoff, retain the bounded rollback set and retire exact superseded, failed, temporary, and orphaned project-owned runtime resources. Persistent/shared dependencies are never superseded merely because application code changed.
120
142
 
121
- Ordinary failure uses forward progress: diagnose, repair deployment configuration, restart, or redeploy the same desired release within bounded action budgets. A temporary emergency return to an old release protects availability but does not change desired or count as success.
143
+ Ordinary failure uses forward progress: diagnose, repair project-owned deployment configuration, restart, or redeploy the same desired release within the two-round repair budget. A temporary return to an old release protects availability but does not change desired or count as success.
122
144
 
123
145
  ### 5. Verify and Record
124
146
 
@@ -136,33 +158,39 @@ SUCCEEDED, WAITING_USER, FAILED
136
158
 
137
159
  ### 6. Offer Automation
138
160
 
139
- After deployment has already reached `SUCCEEDED`, detect existing project-native automation and classify the controller/target boundary from observed evidence rather than the Profile ID or environment label. If no automation exists and the user did not request quick or no-confirmation deployment, ask whether the user wants to avoid future full manual deployment runs:
161
+ After deployment has already reached `SUCCEEDED`, detect existing project-native automation and classify the controller/target boundary from observed evidence rather than the Profile ID or environment label. When no suitable automation exists, include one concise recommendation in the terminal success result:
140
162
 
141
- - for a remote Profile backed by a GitHub repository, offer a GitHub Actions CI/CD setup with project-appropriate push, tag/release, or manual trigger policy;
163
+ - for a remote environment backed by a GitHub repository, offer a GitHub Actions CI/CD setup with project-appropriate push, tag/release, or manual trigger policy;
142
164
  - for another remote repository, offer only an equivalent supported by current project/host evidence;
143
- - for a local Profile, offer project-native watch/hot reload, incremental restart, container sync/watch, or a lightweight commit-triggered local deploy.
165
+ - for a local environment, offer project-native watch/hot reload, incremental restart, container sync/watch, or a lightweight commit-triggered local deploy.
144
166
 
145
- Automation setup is optional and separate from the completed deployment. A decline or setup failure does not change `SUCCEEDED`. Do not create a PrizmKit automation-state file; detect automation from project-native workflow/config evidence. Credentials remain in the repository host or target Secret system.
167
+ Automation setup is optional and separate from the completed deployment. In ordinary interaction, the user may accept the recommendation as a new optional operation after deployment succeeds. A decline or setup failure does not change `SUCCEEDED`. Do not create a PrizmKit automation-state file; detect automation from project-native workflow/config evidence. Credentials remain in the repository host or target Secret system.
146
168
 
147
- For quick or no-confirmation deployment, do not turn automation into another question. Include at most one non-blocking automation note in the terminal success result, or omit it when it does not help the requested outcome.
169
+ For quick or no-confirmation deployment, do not turn automation into another question. Always provide the one non-blocking recommendation when suitable automation is absent.
148
170
 
149
171
  ## Output
150
172
 
151
173
  Report:
152
174
 
153
175
  - terminal status and operation;
154
- - selected Profile, target reference, desired and actual live release;
176
+ - selected environment and target reference, plus the internal Profile record result when one exists;
177
+ - for failed SSH access, the observed failure class, attempted non-sensitive binding, exact missing connection fact or durable server/cloud configuration change, and one retry action;
178
+ - desired and actual live release;
155
179
  - concise verification observations and residual resources;
156
180
  - rollback availability without treating it as required approval;
157
- - Profile record result;
158
181
  - one exact recovery action for `WAITING_USER`, or the evidence-backed failure reason;
159
- - optional automation offer only after successful convergence.
182
+ - one non-blocking automation recommendation after successful convergence when suitable automation is absent.
160
183
 
161
184
  Bound and redact all output. A command exit, queued control-plane request, healthy old release, or completed rollback is not proof that the desired deployment succeeded.
162
185
 
186
+ ## Interaction Examples
187
+
188
+ - Clean worktree plus configured default environment: resolve the environment, deploy, repair if needed, verify, and return `SUCCEEDED` without a blocking question.
189
+ - Dirty worktree: return one action such as “Choose this deployment's Release source: current worktree, current commit, or stop.” Resume the same operation from the selected source.
190
+
163
191
  ## Conditional Reference Loading
164
192
 
165
- Load only the branch needed now:
193
+ Load only the branch needed now. The controller branch and matching playbook are selected in §Deployment Unit, Environment, and Fast Path.
166
194
 
167
195
  - action derivation or evidence conflict → `${SKILL_DIR}/references/capability-contract.md`
168
196
  - write, material work, migration, redeploy, dependency, promotion, or automation setup → `${SKILL_DIR}/references/policy-and-execution.md`
@@ -170,4 +198,4 @@ Load only the branch needed now:
170
198
  - Profile record read/write → `${SKILL_DIR}/references/deploy-record-schema.json` through the single artifact validator
171
199
  - declaration read/write → `${SKILL_DIR}/references/deployment-declaration-schema.json` through the single artifact validator
172
200
  - existing legacy evidence → `${SKILL_DIR}/references/legacy-migration.md`
173
- - an explicitly requested real external-resource test rather than an ordinary selected-Profile deployment → `${SKILL_DIR}/references/real-resource-test-policy.md`
201
+ - an explicitly requested real external-resource test rather than an ordinary selected-environment deployment → `${SKILL_DIR}/references/real-resource-test-policy.md`
@@ -27,13 +27,11 @@ Lower evidence may identify what to inspect but cannot override current direct o
27
27
 
28
28
  A maintained recipe is reusable only while its project, tool, target, artifact, command, health, ownership, resource, and cleanup fingerprint matches. Otherwise derive the action from current project evidence, real capability evidence, and applicable official documentation. A product name or remembered command is never enough for a write.
29
29
 
30
- ## Direct Remote-Machine Transport
30
+ ## Concrete Controller Input
31
31
 
32
- When the selected target is a directly managed remote machine with shell access, choose the installed `ssh` executable as the default implementation of `connect`. Derive its destination and options from current project-native evidence, an observed or user-supplied SSH config alias, or the confirmed target decision. Do not derive connection details from a Profile/environment name, and do not guess a host, user, port, key path, or jump host.
32
+ Select concrete controller guidance through `${SKILL_DIR}/references/fast-path-selection.md` and its matching playbook before deriving a material action. The playbook supplies observed command knowledge; this contract still owns semantic action fields, evidence, effects, Gates, and verification.
33
33
 
34
- Build the connection action as an executable plus separate arguments and prefer an exact bounded remote command, for example the semantic shape `ssh <destination> <remote-command>`, over an unmanaged interactive session. Reuse the established SSH config, authentication agent/key reference, proxy path, and host-key verification. Once the destination resolves, run one bounded non-interactive probe before concluding that authentication requires the user; successful established credentials authorize immediate observation and continuation. An SSH-backed transfer executable is eligible only when installed capability proves it and it preserves the same destination, identity, and effect boundary.
35
-
36
- SSH is a transport default, not a protocol route. Do not force it onto a local target, an API/control-plane-only target, or a project whose authoritative native deployment path provides no host shell. Do not disable or silently bypass host-key verification. A first-seen or changed key without trusted fingerprint evidence is a target-identity conflict. Create a Human Checkpoint for login, MFA, key enrollment, or another authentication action only after current non-interactive methods cannot complete it.
34
+ For a direct remote target, load `${SKILL_DIR}/references/playbook-remote-runtime.md`. When that target exposes shell access, the installed `ssh` executable is the default implementation of semantic `connect`; a browser dashboard or web terminal is not an equivalent transport. Explicit permission to use local SSH credentials resolves the credential-use decision: allow SSH to use the selected target's configured alias, agent, and key files without another question, while never reading or exposing private-key material. Browser automation is considered only for an exact authoritative control-plane operation with no supported project-native command, API, CLI, or SSH path. An SSH authentication failure does not authorize a silent transport change. A remote playbook cannot bypass target identity, host-key, authentication, ownership, or unknown-outcome boundaries.
37
35
 
38
36
  ## Base Action Contract
39
37
 
@@ -47,9 +45,18 @@ Every selected automatic or human action contains only these base facts:
47
45
  | `action` | Complete executable plus arguments, target-native action, or one exact human action. |
48
46
  | `verification` | Observable required and optional postconditions for this action. |
49
47
 
50
- Keep executable and arguments separate where possible. Use project-relative working directories and inject Secret material through user- or target-owned systems. Never interpolate an untrusted value into an opaque shell command.
48
+ Keep executable and arguments separate where possible. Use project-relative working directories and external Secret systems because opaque interpolation can expose credentials or change command meaning.
49
+
50
+ Classify an action as automatic only when current evidence proves its target, effects, ownership, finite resource behavior, executable shape, and verification. Treat an explicit user decision for one fully identified action and effect, including no-confirmation or no-backup intent, as a resolved Gate decision within the user's established authority.
51
+
52
+ Before creating a Human Checkpoint:
53
+
54
+ 1. complete bounded read-only discovery;
55
+ 2. resolve any unique evidence-backed target;
56
+ 3. try established non-interactive authentication;
57
+ 4. honor an explicit decision already made for the exact identified effect.
51
58
 
52
- An action is automatic when current evidence proves its executable shape, target, effects, ownership, bounded resource behavior, and verification inside the standard deployment envelope. Treat an explicit user decision for one fully identified action and effect, including no-confirmation or no-backup intent, as a resolved Gate decision within the user's established authority; do not convert it into another Human Checkpoint. Before creating a Human Checkpoint, perform bounded read-only discovery, resolve any single evidence-backed target, and try established non-interactive authentication. Only when a person must still authenticate, choose among unresolved targets, decide an irreversible or insufficiently bounded data effect not already accepted for the exact action, or resolve shared ownership, represent one exact human action and expected postcondition. Missing facts, unresolved identity, unbounded impact, and unproven ownership remain information boundaries because user intent cannot make them known. When no safe action can be established, report the missing evidence or unsupported capability instead of fabricating a command.
59
+ Return one human action only when identity, target, irreversible or unbounded data effect, or shared ownership still requires a person. For failed SSH access, classify the observed resolver, network, host-key, authentication, service, or remote-authorization failure and request only the missing durable connection fact or configuration change; never delegate the deployment commands to the user. Missing facts and unproven ownership remain information boundaries because user intent cannot make them known. When no safe action can be established, report the missing evidence or unsupported capability instead of fabricating a command.
53
60
 
54
61
  Evidence derivation basis such as maintained recipe or current dynamic derivation is internal provenance, not a user-visible deployment status and not a risk classification.
55
62
 
@@ -78,7 +85,7 @@ Read-only status, health, history, or bounded logs do not require expansion of u
78
85
 
79
86
  Bind every action to one selected Profile, target fingerprint, and desired release when deployment is involved. Actual target state outranks a stale Profile summary. A missing Profile record means no PrizmKit-managed state exists, not that target confirmation is required. Use an explicit request, valid declared default/native configuration, or one unambiguous project-native/SSH target as a provisional locator, inspect it directly, and ask only when no unique non-conflicting target can be resolved. Never assume a first physical deployment.
80
87
 
81
- Prefer an immutable project-native artifact. When test, staging, and production policies allow the same artifact, preserve its identity across Profiles rather than rebuilding. If no artifact mechanism exists, use the current committed revision unless the user separately asks to create a reproducible release from other source state.
88
+ Prefer an immutable project-native artifact. When test, staging, and production policies allow the same artifact, preserve its identity across environments rather than rebuilding. When no artifact mechanism exists and the worktree is clean, use the current committed revision. A dirty worktree requires one release-source action: current worktree with a bounded immutable content identity, current commit, or stop.
82
89
 
83
90
  ## Intent Starting Points
84
91
 
@@ -0,0 +1,51 @@
1
+ # Evidence-Driven Deployment Fast Paths
2
+
3
+ Use this reference after interpreting the operation and candidate environment, before deriving deployment actions. The resolver chooses concrete operational guidance while semantic capabilities remain the stable protocol.
4
+
5
+ ## Default Model
6
+
7
+ Treat the project as one deployable unit unless current project-native configuration proves independent deployment targets or lifecycles. One unit may have local, test, staging, production, or custom environments.
8
+
9
+ Resolve the environment from:
10
+
11
+ 1. the user's explicit environment or target;
12
+ 2. the valid project-configured default;
13
+ 3. one project-native default target;
14
+ 4. one unambiguous previously observed target;
15
+ 5. one user selection action when multiple candidates remain and no default resolves them.
16
+
17
+ Do not create a user-visible Profile setup step. Derive the internal Profile identity after observing the target.
18
+
19
+ ## Controller Precedence
20
+
21
+ Select the smallest authoritative controller in this order:
22
+
23
+ 1. explicit target/control method requested by the user;
24
+ 2. existing project-native deployment command, workflow, or controller;
25
+ 3. controller of the observed live deployment;
26
+ 4. repository-hosting, container, remote-runtime, process, or proxy evidence;
27
+ 5. generic fallback.
28
+
29
+ The presence of several configuration files does not mean every controller should run. Resolve conflicts through current live state and one bounded read-only observation.
30
+
31
+ ## Connection Transport Precedence
32
+
33
+ Controller selection and connection transport are separate decisions. A project-native controller may remain authoritative when it internally owns transport. Otherwise, when a directly managed machine exposes or is configured for shell access, use the installed `ssh` executable and the verified SSH binding as the default transport for observation, transfer, execution, and verification. When the user authorizes local SSH credentials, resolve only the selected target's alias/configuration and let SSH try its configured agent and key files without another permission question; do not enumerate unrelated hosts or reveal key material.
34
+
35
+ A cloud provider dashboard does not make a server a repository-hosted deployment target. Browser automation—for example, a browser-driving test tool—is a last-resort control-plane adapter, not a remote-shell transport. Use it only when the exact authoritative operation has no supported project-native command, API, CLI, or SSH path. Never type deployment commands into a web terminal or upload a Release through a dashboard when an SSH binding exists or can be established. If SSH reaches a user-only authentication boundary, diagnose it and return one exact durable connection-enablement action instead of silently switching to a browser console or asking the user to execute the deployment remotely.
36
+
37
+ ## Conditional Playbook Loading
38
+
39
+ - project-native controller → `playbook-project-native.md`
40
+ - repository-hosted controller → `playbook-repository-hosted.md`
41
+ - container controller → `playbook-container.md`
42
+ - direct remote/runtime/proxy controller → `playbook-remote-runtime.md`
43
+ - no specialized match → `playbook-generic-fallback.md`
44
+
45
+ Load a second playbook only when selected-command expansion exposes a material child controller that the primary playbook cannot fully establish.
46
+
47
+ ## Playbook Contract
48
+
49
+ Each playbook establishes activation evidence, target observations, semantic action mapping, verification, bounded repairs, rollback/cleanup behavior, and user-only boundaries. A playbook supplies operational knowledge but cannot bypass the Capability contract, conditional Gates, or terminal verification.
50
+
51
+ Provider and tool names are non-exhaustive evidence examples. A remembered product command without matching project, target, version, authentication, effect, and verification evidence is not executable authority.
@@ -0,0 +1,26 @@
1
+ # Container Deployment Playbook
2
+
3
+ Use this playbook when an observed image or multi-service container controller owns the selected environment.
4
+
5
+ ## Discovery
6
+
7
+ Read the current image build file, compose/orchestration configuration, service dependencies, ports, health definitions, volumes, networks, Secret references, and controller executable/version. Docker, Compose, Podman, and compatible tools are non-exhaustive examples.
8
+
9
+ Render or validate configuration through the installed controller when supported; for example, use `docker compose config` only when current help and project configuration prove that command.
10
+
11
+ ## Build and Handoff
12
+
13
+ 1. Build or reuse one image identity for the fixed Release and observed toolchain.
14
+ 2. Inventory exact project-owned containers, images, networks, candidates, rollback units, and persistent volumes.
15
+ 3. When coexistence is supported, start a candidate without disturbing old live, verify it, then switch the native selector.
16
+ 4. When only in-place replacement exists, disclose bounded downtime and continue inside the standard deployment envelope.
17
+ 5. Verify Release identity, replicas, ports, required health, and live routing.
18
+ 6. Remove only exact superseded, failed, and temporary project-owned resources.
19
+
20
+ Never use global image, volume, or system pruning as deployment cleanup. Persistent volumes and shared networks are not superseded application runtime.
21
+
22
+ ## Repair and Operations
23
+
24
+ Repair project-owned build context, image configuration, compose syntax, service startup, port mapping, and health configuration when evidence proves a bounded defect. Use native scoped status, logs, restart, and rollback commands with observed service and project identities.
25
+
26
+ For local environments, recommend native watch, file synchronization, or incremental rebuild when supported instead of remote CI/CD.
@@ -0,0 +1,22 @@
1
+ # Generic Deployment Fallback
2
+
3
+ Use this playbook when no specialized controller playbook matches current evidence.
4
+
5
+ ## Bounded Discovery
6
+
7
+ Identify the build output, start behavior, ports, environment-variable names, target control interface, current runtime, Release identity, live selector, and minimum verification boundary from project and target evidence.
8
+
9
+ When those facts establish a bounded action, map the shortest action sequence to semantic capabilities and continue through the normal policy and verification kernel.
10
+
11
+ When one indispensable fact is missing, return exactly one target, authentication, release-source, data-effect, or ownership action. Do not replace missing evidence with a conventional command or endpoint.
12
+
13
+ ## Unsupported Outcome
14
+
15
+ If no safe controller can be established, report:
16
+
17
+ - observed project and target facts;
18
+ - the unsupported capability or adapter gap;
19
+ - target state and any residual resources;
20
+ - one exact safe continuation when available.
21
+
22
+ A deployment guide or manual checklist may be produced when the user requests documentation or automatic deployment cannot complete. Documentation remains auxiliary output and never changes an unverified deployment to `SUCCEEDED`.
@@ -0,0 +1,24 @@
1
+ # Project-Native Deployment Playbook
2
+
3
+ Use this playbook when the project already defines the selected deploy, release, status, health, logs, restart, or rollback controller.
4
+
5
+ ## Activation Evidence
6
+
7
+ Evidence may include package-manager scripts, Make/Task targets, executable project scripts, deployment manifests, repository workflows, or documented project commands. Examples such as `npm run deploy`, `make deploy`, or `task deploy` are eligible only when the current project defines them.
8
+
9
+ ## Derivation
10
+
11
+ 1. Identify the exact working directory, environment input, Release source, authentication references, and expected target.
12
+ 2. Expand the selected command through aliases and material child scripts until every branch reaches a known executable, target-native action, or human boundary.
13
+ 3. Reuse project-native status, health, logs, rollback, and cleanup commands when their scope matches the selected environment.
14
+ 4. Map the observed command effects to semantic capabilities and conditional Gates before execution.
15
+
16
+ Do not invent an undocumented flag or run an opaque wrapper to discover its effects.
17
+
18
+ ## Repair and Verification
19
+
20
+ Repair project-owned deployment scripts or configuration when current parser, validation, help, or execution evidence identifies a bounded deployment defect. Do not change application business logic.
21
+
22
+ Verify the actual target, Release identity, live selector, required health, and owned residual resources after the project-native command completes. A command exit or queued workflow is not deployment success.
23
+
24
+ An existing deployment script is not by itself CI/CD. Classify automation only when current project evidence proves an automatic trigger and target handoff.
@@ -0,0 +1,54 @@
1
+ # Direct Remote Runtime Playbook
2
+
3
+ Use this playbook when the selected environment is a directly managed remote machine or when an observed process supervisor or reverse proxy owns runtime handoff.
4
+
5
+ ## Connection
6
+
7
+ Use the installed `ssh` executable as the default implementation of semantic `connect` when the target exposes shell access. This includes a cloud server, virtual machine, or directly managed host even when its provider also offers a dashboard. Derive the destination from an explicit target, project evidence, or an observed/user-supplied SSH config alias. Reuse its user, port, proxy, agent/key, and host-verification settings.
8
+
9
+ A provider dashboard or browser-accessible terminal does not outrank SSH. Do not use browser automation to type into a web shell, upload the application, execute deployment commands, or inspect ordinary runtime state when the verified SSH binding can perform the operation. Browser automation—for example, a Playwright-driven dashboard—is eligible only for an exact provider control-plane operation that has no supported project-native command, API, CLI, or SSH path.
10
+
11
+ ### Authorized Local Credential Path
12
+
13
+ When the user authorizes local SSH credential use, proceed without another key-use question:
14
+
15
+ 1. Resolve only the selected destination's effective configuration with the installed SSH client, such as `ssh -G <verified-destination>`; do not enumerate unrelated aliases.
16
+ 2. When relevant, inspect only public agent fingerprints through `ssh-add -l`. Let SSH use the configured agent and `IdentityFile` paths; never read, copy, print, or upload private-key contents.
17
+ 3. Attempt one bounded non-interactive probe through the resolved binding, equivalent to `ssh -o BatchMode=yes -o ConnectTimeout=<bounded-seconds> <verified-destination> true`. Preserve ordinary host-key checking and bounded diagnostics.
18
+ 4. Continue immediately through the same binding when the probe succeeds. Do not ask the user to confirm SSH again.
19
+
20
+ Do not guess host, user, port, key path, bastion, or fingerprint, and do not bypass host-key verification. Use a project-native controller instead when the target exposes no shell or defines another authoritative path.
21
+
22
+ ### Connection Failure Diagnosis
23
+
24
+ Diagnose a failed probe before returning `WAITING_USER`:
25
+
26
+ | Observed failure | Durable information or configuration needed |
27
+ |---|---|
28
+ | destination absent or name resolution failed | SSH alias or hostname/IP, login user, port, and any required proxy, bastion, VPN, or private-network route |
29
+ | timeout or no route | reachable address/network path and the cloud security-group or firewall inbound rule for the selected SSH port and trusted source |
30
+ | connection refused | correct SSH port plus an enabled/listening SSH service and non-rejecting host firewall |
31
+ | unknown or changed host key | trusted expected host-key fingerprint, or verified key-rotation evidence before updating local trust |
32
+ | no usable local identity or encrypted key unavailable | target-specific SSH `IdentityFile`/agent configuration or a locally unlocked agent identity; never request the private key or passphrase in chat |
33
+ | public-key authentication denied | correct login user and registration of the matching local public-key fingerprint in the account's authorized-key or cloud-managed SSH-key configuration, with public-key authentication enabled |
34
+ | connected user lacks project access | deploy username, project-owned remote directory, and the minimum durable file/runtime/supervisor permission or bounded privilege policy |
35
+ | target intentionally exposes no shell | the authoritative project-native API, CLI, or controller binding instead of browser-emulated shell access |
36
+
37
+ Return exactly one connection-enablement action containing only the applicable missing facts or configuration changes and the instruction to retry. Explain the observed failure safely, but do not ask the user to log into the server and run deployment commands; after access is enabled, this Skill reconnects and performs those operations itself. Do not switch to a browser console merely because SSH authentication or reachability failed.
38
+
39
+ ## Build, Transfer, and Runtime
40
+
41
+ 1. Observe the project-owned remote directory, current Release, live selector, runtime units, configured health, and exact residual resources without broad host inventory.
42
+ 2. Prefer transfer or promotion of an immutable project artifact. If the target builds or pulls source, bind the exact source identity and inject required build-time environment before building.
43
+ 3. Detect the existing runtime controller rather than installing one. Examples such as systemd, PM2, container runtimes, and equivalent supervisors are eligible only after current target evidence proves their ownership and command shape.
44
+ 4. Check candidate ports and current owners before starting a parallel runtime.
45
+ 5. When a reverse proxy or live selector is observed, validate its candidate configuration with the controller's native syntax check before switching. Examples such as `nginx -t` or `caddy validate` require the corresponding observed controller.
46
+ 6. Verify the candidate, switch live, verify through the live path, then retire exact superseded runtime according to rollback policy.
47
+
48
+ Do not automatically install or replace global packages, users, firewalls, certificates, proxies, or supervisors. Those effects require established project ownership and the applicable Gate.
49
+
50
+ ## Repair and Recovery
51
+
52
+ Bounded repairs may correct project-owned remote paths, permissions, startup parameters, build-time environment references, candidate ports, supervisor configuration, and proxy blocks. A disconnect during a possible write triggers rediscovery through the same verified destination before replay.
53
+
54
+ If post-handoff verification fails and return to the retained proven Release is safe, restore and verify old live immediately. The desired Release remains pending for diagnosis and bounded repair.
@@ -0,0 +1,23 @@
1
+ # Repository-Hosted Deployment Playbook
2
+
3
+ Use this playbook when an observed hosting control plane owns build, release, promotion, traffic, or runtime operations and the project contains matching native configuration or binding evidence. A cloud server or virtual machine does not match merely because its provider has a web dashboard; when the project directly owns the machine and shell access is established, use the remote-runtime playbook and SSH.
4
+
5
+ ## Discovery
6
+
7
+ 1. Inspect native project configuration and local project-binding metadata.
8
+ 2. Verify the installed controller executable, version, supported help, current authentication identity, organization/project binding, and selected environment.
9
+ 3. Observe current deployments, aliases, promotion state, and configured environment-variable names without displaying Secret values.
10
+
11
+ Tools such as Vercel, Netlify, Fly.io, and similar repository-hosted platforms are non-exhaustive examples. Commands such as `vercel deploy --prod`, `netlify deploy --prod`, or `fly deploy` may be used only when installed capability, current binding, and applicable official evidence prove the exact shape for the selected target.
12
+
13
+ ## Deploy and Operate
14
+
15
+ Use the native controller to create or promote the fixed desired Release, observe an asynchronous request until terminal, then verify deployment identity, alias/live selection, configured health, and public-path behavior when required.
16
+
17
+ Use native status, bounded logs, restart/redeploy, and rollback operations when the observed controller supports them. Keep credentials in the host's Secret or environment system.
18
+
19
+ ## Repair and User Boundaries
20
+
21
+ Repair project-owned hosting configuration, build settings, output paths, and environment-variable references when current evidence identifies the defect. Authentication login, MFA, unresolved account/project selection, billing boundary, and unknown shared-domain ownership remain user actions.
22
+
23
+ After success, recommend host-compatible CI/CD when no automatic repository trigger exists.
@@ -10,7 +10,7 @@ An explicit deploy invocation authorizes the selected Profile's standard deploym
10
10
 
11
11
  The standard envelope covers project-owned, bounded actions needed to build/package, resolve project-declared dependencies, apply non-destructive native migrations, create a candidate, start/restart, hand off live traffic, verify, retain bounded rollback when not explicitly declined, retire exact old runtime resources, clean failed/temporary resources, and update the selected Profile record.
12
12
 
13
- For a selected directly managed remote machine, connecting and running bounded project-scoped actions through the established SSH destination are part of that standard envelope. Do not ask for another confirmation merely because the next executable is `ssh`; use established non-interactive credentials first. A missing Profile record or ordinary first deployment also does not create a checkpoint when one non-conflicting target resolves from current evidence.
13
+ For a selected directly managed remote machine, connecting and running bounded project-scoped actions through the established SSH destination are part of that standard envelope. Do not ask for another confirmation merely because the next executable is `ssh`; use established non-interactive credentials first. Explicit permission to use local SSH credentials authorizes the installed SSH client to consume the selected target's configured alias, agent, and key files without another question, but never authorizes reading or exposing private-key values. A missing Profile record or ordinary first deployment also does not create a checkpoint when one non-conflicting target resolves from current evidence.
14
14
 
15
15
  ### User Intent and Fast Completion
16
16
 
@@ -51,11 +51,13 @@ Do not run a material producer when current project-native evidence already cove
51
51
 
52
52
  For each selected SSH action, preserve the verified destination, authentication identity, proxy path, host-key evidence, and project-owned working boundary used during discovery. Execute the smallest exact remote command needed for the current difference, with bounded connection/action time and output. Reuse one proven connection binding across observation, transfer, write, and verification instead of silently changing users or endpoints between steps.
53
53
 
54
- Do not pass Secret values in command arguments, print private-key material, start a broad remote inventory, or bypass host-key verification. Attempt one bounded non-interactive connection with the established SSH configuration before deciding authentication cannot complete; continue immediately when it succeeds. Only then return one exact `WAITING_USER` authentication action when user input is unavoidable. If the target key or destination differs from established evidence, treat it as an identity conflict rather than a transient retry. After a disconnect during a possible write, use the same verified SSH destination to inspect actual state before considering replay.
54
+ When local credential use is authorized, perform target-scoped discovery through the SSH client: resolve the selected destination's effective configuration, inspect available agent public-key fingerprints when relevant, and let SSH select its configured key files. Do not open private-key files to obtain their contents, enumerate unrelated host aliases or keys, or print local credential paths in the result.
55
+
56
+ Do not pass Secret values in command arguments, print private-key material, start a broad remote inventory, or bypass host-key verification. Attempt one bounded non-interactive connection with the established SSH configuration before deciding authentication cannot complete; continue immediately when it succeeds. If it fails, preserve bounded safe diagnostics and classify whether the cause is unresolved destination, name resolution, timeout/no route, connection refusal, host-key trust/conflict, unavailable local key/agent, public-key denial, SSH service policy, or connected-user authorization. Only then return one exact `WAITING_USER` connection-enablement action when user input is unavoidable. State the exact missing server fact or cloud/server configuration change needed for durable automatic access, then retry and perform the server work through SSH; never ask the user to log in and run deployment commands. If the target key or destination differs from established evidence, treat it as an identity conflict rather than a transient retry. After a disconnect during a possible write, use the same verified SSH destination to inspect actual state before considering replay.
55
57
 
56
58
  ## Current → Desired Loop
57
59
 
58
- For one selected Profile:
60
+ For one selected environment and its internal Profile record:
59
61
 
60
62
  1. Observe authoritative target state, project revision, automation, live selector, owned resources, persistent/shared dependencies, and existing reusable evidence.
61
63
  2. Bind the Profile policy's latest eligible desired release and keep it fixed for this operation.
@@ -86,9 +88,11 @@ Prefer an evidence-supported candidate/handoff transition:
86
88
 
87
89
  Use in-place replacement only when the target lacks coexistence and its downtime/data effects are known. Missing rollback alone does not pause, but irreversible data or unknown/shared effects do.
88
90
 
89
- Candidate failure before handoff preserves old live and cleans exact candidate resources. A post-handoff ordinary failure follows forward progress for the same desired release. Emergency isolation or a temporary traffic return is allowed only to contain data, security, or ongoing user harm; it is not terminal deployment success.
91
+ Candidate failure before handoff preserves old live and cleans exact candidate resources.
92
+
93
+ After handoff, a required verification failure returns the live selector to the retained proven release immediately when current evidence proves reversal is safe. Verify restored availability, then diagnose and repair the still-desired release. If reversal itself has unresolved data or shared-resource effects, contain ongoing harm and return one exact decision instead of guessing.
90
94
 
91
- Persistent data, shared infrastructure, and unproven resources are never classified as old application runtime merely because code changed.
95
+ Restoring old live protects availability but does not change the desired release or count as deployment success. Persistent data, shared infrastructure, and unproven resources are never classified as old application runtime merely because code changed.
92
96
 
93
97
  ## Data and Dependency Gates
94
98
 
@@ -104,11 +108,13 @@ When the project produces an immutable artifact, build it once for one source/to
104
108
 
105
109
  A production-like Profile may require an artifact already verified by another Profile. Promotion still observes the destination current state and performs only its missing transfer/release/configure/handoff/verification work.
106
110
 
107
- When no artifact mechanism exists, use the current committed revision and the minimum project-native producer. Do not silently include dirty workspace content.
111
+ When no artifact mechanism exists, use the current committed revision only when the worktree is clean. A dirty worktree pauses for one release-source action. If current worktree is selected, create a bounded immutable content identity without committing or including ignored files and Secrets.
108
112
 
109
113
  ## Retry, Unknown Outcomes, and Forward Work
110
114
 
111
- Retry only a proven read-only or idempotent action for a transient condition within its aggregate attempt/resource budget. After attempts are exhausted, select a bounded diagnostic or a different proven forward action; do not reset the same wrapper into an open loop.
115
+ Each failing deployment step receives one initial execution and at most two evidence-supported repair rounds. Re-observe the target before each round. A repair round may choose a smaller or corrected action; it does not blindly replay the failed wrapper.
116
+
117
+ Replay only a proven read-only or idempotent action whose current evidence shows the intended effect did not occur. Do not repeat the same failure without new evidence or reset the two-round budget through another wrapper. After the budget is exhausted, select a bounded diagnostic or a different proven forward action only when that action closes a newly observed difference.
112
118
 
113
119
  After timeout, disconnect, or lost response during a possible write, inspect current target state before replay:
114
120
 
@@ -126,9 +132,11 @@ Bound logs by source, purpose, time and/or line count. Prefer omission when reli
126
132
 
127
133
  ## Post-Success Automation
128
134
 
129
- Offer automation only after deployment has already reached `SUCCEEDED` and only when project-native evidence shows no suitable automation exists. The offer is a separate optional project-file change, not a condition of deployment success. For quick or no-confirmation deployment, do not ask another question; include at most one non-blocking automation note in the terminal result or omit it.
135
+ Assess automation only after deployment has already reached `SUCCEEDED`. When project-native evidence shows no suitable automation exists, the terminal result always includes one concise, target-compatible recommendation. The recommendation is not a condition of deployment success.
136
+
137
+ In ordinary interaction, ask whether to configure automation only after reporting deployment success; acceptance starts a separate optional project-file operation. For quick or no-confirmation deployment, provide the recommendation without asking another question.
130
138
 
131
- ### Remote Profile
139
+ ### Remote Environment
132
140
 
133
141
  When repository evidence identifies GitHub and the target supports non-interactive deployment, offer GitHub Actions. Ask the user whether to configure it and derive the trigger from project release policy; if no policy resolves main-branch, tag/release, or manual dispatch behavior, ask one trigger question.
134
142
 
@@ -136,11 +144,11 @@ Separate quick push and pull-request checks from CD. CD should reuse a verified
136
144
 
137
145
  For another repository host, offer only a semantically equivalent automation proven by current project and host capability. Do not route by provider name alone.
138
146
 
139
- ### Local Profile
147
+ ### Local Environment
140
148
 
141
149
  Do not create remote CI/CD for local deployment. Offer the best existing project-native local loop in this order when supported: watch or hot reload, incremental build and restart, container file sync/watch, then a lightweight commit-triggered local deploy.
142
150
 
143
- Local automation affects only the selected local Profile. It does not run production migration, access a remote Profile, or execute a complete release-candidate/production ring on every file save. When no incremental capability exists, keep manual one-click deploy rather than inventing scripts.
151
+ Local automation affects only the selected local environment. It does not run production migration, access a remote environment, or execute a complete release-candidate/production ring on every file save. When no incremental capability exists, keep manual one-click deploy rather than inventing scripts.
144
152
 
145
153
  Do not create a PrizmKit automation-state artifact. Detect automation from project-native workflow/config files. A declined or failed setup does not change the completed deployment result.
146
154
 
@@ -55,7 +55,7 @@ On an ordinary failure, keep the desired release fixed and preserve evidence abo
55
55
 
56
56
  A temporary return to the previous release is not deployment success. Use emergency isolation or temporary old traffic only to contain data damage, security exposure, or continuing user harm. The desired release remains pending until it becomes live and converged or no safe path exists.
57
57
 
58
- Each individual action has a finite attempt/resource budget. Forward progress can choose a different proven action after a budget is exhausted, but it never converts retries into an unbounded loop.
58
+ Each failing step has one initial action and at most two evidence-supported repair rounds. Re-observe before each round. A different proven action may use the remaining budget, but wrappers cannot reset the limit or convert retries into an unbounded loop.
59
59
 
60
60
  ## Failure Boundaries
61
61
 
@@ -69,11 +69,11 @@ Keep the proven old release live. Diagnose or clean only the exact failed candid
69
69
 
70
70
  ### After Handoff
71
71
 
72
- Observe the actual selector and both release states before repair, retirement, or emergency traffic protection. Prefer repair/restart/redeploy of desired. Never remove persistent/shared dependencies or hide failed convergence by deleting unexplained resources.
72
+ Observe the actual selector and both release states. When return to the retained proven release is supported and safe, restore and verify old live immediately, then diagnose and repair the still-desired release. If reversal has unresolved data or shared-resource effects, contain harm and return one exact action. Never remove persistent/shared dependencies or hide failed convergence by deleting unexplained resources.
73
73
 
74
74
  ### Required Health Failure
75
75
 
76
- A required health failure prevents `SUCCEEDED`, but it does not force terminal rollback. Observe current state and continue through a different bounded forward action when available. Emergency protection remains temporary and does not complete the desired deployment.
76
+ A required health failure prevents `SUCCEEDED`. Before handoff, keep old live and repair the candidate. After handoff, restore the retained proven release when reversal is safe, verify availability, and continue bounded diagnosis of the desired release. The restoration is not terminal deployment success.
77
77
 
78
78
  ### Profile Record Failure
79
79
 
@@ -109,7 +109,7 @@ Return exactly one status:
109
109
  | Status | Condition |
110
110
  |---|---|
111
111
  | `SUCCEEDED` | Desired release is live when deployment applies, all required observations pass, required inventory converges, and no effect needed for correctness remains unknown. |
112
- | `WAITING_USER` | Exactly one identity, target, unresolved data-effect, shared/ownership, source-fix, or indeterminate-outcome action can resume the same desired operation. |
112
+ | `WAITING_USER` | Exactly one identity, target, release-source, unresolved data-effect, shared/ownership, source-fix, or indeterminate-outcome action can resume the same desired operation. |
113
113
  | `FAILED` | No safe continuation exists, the desired release is unsupported/unrecoverable within scope, or the user stopped the operation. |
114
114
 
115
115
  A release may be live while a Profile record update failed; state both facts. A healthy old release, completed rollback, or partially live candidate never converts an incomplete desired deployment to `SUCCEEDED`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prizmkit",
3
- "version": "1.1.171",
3
+ "version": "1.1.174",
4
4
  "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
5
5
  "type": "module",
6
6
  "bin": {