prizmkit 1.1.171 → 1.1.173
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.
- package/bundled/VERSION.json +3 -3
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/prizmkit-deploy/SKILL.md +64 -45
- package/bundled/skills/prizmkit-deploy/references/capability-contract.md +15 -8
- package/bundled/skills/prizmkit-deploy/references/fast-path-selection.md +45 -0
- package/bundled/skills/prizmkit-deploy/references/playbook-container.md +26 -0
- package/bundled/skills/prizmkit-deploy/references/playbook-generic-fallback.md +22 -0
- package/bundled/skills/prizmkit-deploy/references/playbook-project-native.md +24 -0
- package/bundled/skills/prizmkit-deploy/references/playbook-remote-runtime.md +26 -0
- package/bundled/skills/prizmkit-deploy/references/playbook-repository-hosted.md +23 -0
- package/bundled/skills/prizmkit-deploy/references/policy-and-execution.md +15 -9
- package/bundled/skills/prizmkit-deploy/references/verification-and-recovery.md +4 -4
- package/package.json +1 -1
package/bundled/VERSION.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: "prizmkit-deploy"
|
|
3
|
-
description: "Deploy
|
|
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 —
|
|
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,33 @@ 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
|
|
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
22
|
|
|
23
23
|
## Invocation and Authority
|
|
24
24
|
|
|
25
25
|
```text
|
|
26
|
-
/prizmkit-deploy
|
|
27
|
-
/prizmkit-deploy <
|
|
28
|
-
/prizmkit-deploy plan
|
|
26
|
+
/prizmkit-deploy → deploy the project default environment
|
|
27
|
+
/prizmkit-deploy <environment> → deploy the named environment
|
|
28
|
+
/prizmkit-deploy plan → discover and preview without writes
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
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.
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
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.
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
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.
|
|
36
|
+
|
|
37
|
+
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.
|
|
36
38
|
|
|
37
39
|
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
40
|
|
|
39
|
-
1.
|
|
40
|
-
2.
|
|
41
|
-
3.
|
|
42
|
-
4.
|
|
41
|
+
1. a release-source choice because tracked or untracked worktree changes exist;
|
|
42
|
+
2. an identity or authentication action only the user can complete after established credentials have been tried;
|
|
43
|
+
3. a target choice that remains absent, conflicting, or ambiguous after current evidence is inspected;
|
|
44
|
+
4. an irreversible data effect not already accepted for this exact target and action, or a data effect that remains insufficiently bounded;
|
|
45
|
+
5. a shared or unknown-ownership resource decision not already resolved within the user's established authority.
|
|
43
46
|
|
|
44
|
-
A missing Profile record, ordinary first deployment, selected-target
|
|
47
|
+
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.
|
|
45
48
|
|
|
46
49
|
## Managed Artifacts
|
|
47
50
|
|
|
@@ -52,47 +55,55 @@ Prefer project-native deployment configuration. PrizmKit owns only:
|
|
|
52
55
|
| `prizmkit.deploy.json` | Optional version-controlled non-sensitive declaration index for Profile hints and policy |
|
|
53
56
|
| `.prizmkit/deploy/profiles/<profile-id>.json` | One local non-sensitive current/result/recovery record per stable Profile |
|
|
54
57
|
|
|
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
|
|
58
|
+
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.
|
|
59
|
+
|
|
60
|
+
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
61
|
|
|
57
|
-
|
|
62
|
+
Validate either managed artifact through one read-only entry point: `python3 ${SKILL_DIR}/scripts/validate-deploy-artifact.py --kind <declaration|record> <path>`.
|
|
58
63
|
|
|
59
|
-
|
|
64
|
+
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
65
|
|
|
61
66
|
When legacy `.prizmkit/deploy/` evidence exists, read `${SKILL_DIR}/references/legacy-migration.md`. Preserve uncertain evidence and stop legacy writers.
|
|
62
67
|
|
|
63
68
|
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
69
|
|
|
65
|
-
##
|
|
70
|
+
## Deployment Unit, Environment, and Fast Path
|
|
71
|
+
|
|
72
|
+
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.
|
|
66
73
|
|
|
67
|
-
|
|
74
|
+
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:
|
|
68
75
|
|
|
69
|
-
|
|
76
|
+
- project-native command or controller → `${SKILL_DIR}/references/playbook-project-native.md`
|
|
77
|
+
- repository-hosted deployment → `${SKILL_DIR}/references/playbook-repository-hosted.md`
|
|
78
|
+
- image or multi-service container deployment → `${SKILL_DIR}/references/playbook-container.md`
|
|
79
|
+
- direct remote machine, process supervisor, or reverse-proxy handoff → `${SKILL_DIR}/references/playbook-remote-runtime.md`
|
|
80
|
+
- no specialized match → `${SKILL_DIR}/references/playbook-generic-fallback.md`
|
|
70
81
|
|
|
71
|
-
|
|
82
|
+
Products and tools are evidence examples, not protocol identifiers. Existing project-native coordination decides whether multiple units deploy together or independently.
|
|
72
83
|
|
|
73
84
|
## AutoDeploy Workflow
|
|
74
85
|
|
|
75
|
-
### 1.
|
|
86
|
+
### 1. Resolve Unit and Environment
|
|
76
87
|
|
|
77
|
-
1.
|
|
78
|
-
2.
|
|
79
|
-
3.
|
|
80
|
-
4. Ask one target
|
|
88
|
+
1. Treat the project as one deployable unit unless project-native evidence proves multiple independent units.
|
|
89
|
+
2. Resolve the explicit or configured default environment automatically.
|
|
90
|
+
3. Inspect one unambiguous target before creating an internal Profile record.
|
|
91
|
+
4. Ask one environment/target action only when no unique target resolves.
|
|
81
92
|
|
|
82
|
-
|
|
93
|
+
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
94
|
|
|
84
|
-
### 2. Observe Current
|
|
95
|
+
### 2. Observe Current and Select a Fast Path
|
|
85
96
|
|
|
86
97
|
Read only the project-native files and target observations needed to establish:
|
|
87
98
|
|
|
88
|
-
- current source/release and the
|
|
99
|
+
- current source/release and the environment policy's latest allowed release;
|
|
89
100
|
- actual target identity, authorization, live selector, runtime units, and configured health;
|
|
90
101
|
- exact project-owned candidates, rollback releases, superseded units, failed attempts, temporary resources, and orphans;
|
|
91
102
|
- persistent/shared dependencies that must not be retired;
|
|
92
103
|
- project-native reports or immutable artifacts that can be reused;
|
|
93
104
|
- selected commands and material child effects through an executable, target-native, or human boundary.
|
|
94
105
|
|
|
95
|
-
|
|
106
|
+
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
107
|
|
|
97
108
|
Read `${SKILL_DIR}/references/capability-contract.md` when selecting or deriving an action.
|
|
98
109
|
|
|
@@ -100,9 +111,10 @@ Read `${SKILL_DIR}/references/capability-contract.md` when selecting or deriving
|
|
|
100
111
|
|
|
101
112
|
Fix one desired release for the operation:
|
|
102
113
|
|
|
103
|
-
1. use the
|
|
104
|
-
2. otherwise use the current committed revision;
|
|
105
|
-
3.
|
|
114
|
+
1. use the environment policy's latest eligible immutable project artifact when available;
|
|
115
|
+
2. otherwise, when the worktree is clean, use the current committed revision;
|
|
116
|
+
3. when the worktree is dirty, return one `WAITING_USER` release-source action with mutually exclusive choices: current worktree, current commit, or stop;
|
|
117
|
+
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
118
|
|
|
107
119
|
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
120
|
|
|
@@ -113,12 +125,14 @@ Read `${SKILL_DIR}/references/policy-and-execution.md` before a write or materia
|
|
|
113
125
|
1. compute the current → desired difference;
|
|
114
126
|
2. choose the smallest evidence-supported next action;
|
|
115
127
|
3. activate only the conditional Gates implicated by that action;
|
|
116
|
-
4. execute
|
|
128
|
+
4. execute once, then allow at most two evidence-supported repair rounds for that failing step;
|
|
117
129
|
5. observe the result before selecting another action.
|
|
118
130
|
|
|
131
|
+
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.
|
|
132
|
+
|
|
119
133
|
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
134
|
|
|
121
|
-
Ordinary failure uses forward progress: diagnose, repair deployment configuration, restart, or redeploy the same desired release within
|
|
135
|
+
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
136
|
|
|
123
137
|
### 5. Verify and Record
|
|
124
138
|
|
|
@@ -136,33 +150,38 @@ SUCCEEDED, WAITING_USER, FAILED
|
|
|
136
150
|
|
|
137
151
|
### 6. Offer Automation
|
|
138
152
|
|
|
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.
|
|
153
|
+
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
154
|
|
|
141
|
-
- for a remote
|
|
155
|
+
- 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
156
|
- for another remote repository, offer only an equivalent supported by current project/host evidence;
|
|
143
|
-
- for a local
|
|
157
|
+
- for a local environment, offer project-native watch/hot reload, incremental restart, container sync/watch, or a lightweight commit-triggered local deploy.
|
|
144
158
|
|
|
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.
|
|
159
|
+
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
160
|
|
|
147
|
-
For quick or no-confirmation deployment, do not turn automation into another question.
|
|
161
|
+
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
162
|
|
|
149
163
|
## Output
|
|
150
164
|
|
|
151
165
|
Report:
|
|
152
166
|
|
|
153
167
|
- terminal status and operation;
|
|
154
|
-
- selected
|
|
168
|
+
- selected environment and target reference, plus the internal Profile record result when one exists;
|
|
169
|
+
- desired and actual live release;
|
|
155
170
|
- concise verification observations and residual resources;
|
|
156
171
|
- rollback availability without treating it as required approval;
|
|
157
|
-
- Profile record result;
|
|
158
172
|
- one exact recovery action for `WAITING_USER`, or the evidence-backed failure reason;
|
|
159
|
-
-
|
|
173
|
+
- one non-blocking automation recommendation after successful convergence when suitable automation is absent.
|
|
160
174
|
|
|
161
175
|
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
176
|
|
|
177
|
+
## Interaction Examples
|
|
178
|
+
|
|
179
|
+
- Clean worktree plus configured default environment: resolve the environment, deploy, repair if needed, verify, and return `SUCCEEDED` without a blocking question.
|
|
180
|
+
- 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.
|
|
181
|
+
|
|
163
182
|
## Conditional Reference Loading
|
|
164
183
|
|
|
165
|
-
Load only the branch needed now
|
|
184
|
+
Load only the branch needed now. The controller branch and matching playbook are selected in §Deployment Unit, Environment, and Fast Path.
|
|
166
185
|
|
|
167
186
|
- action derivation or evidence conflict → `${SKILL_DIR}/references/capability-contract.md`
|
|
168
187
|
- write, material work, migration, redeploy, dependency, promotion, or automation setup → `${SKILL_DIR}/references/policy-and-execution.md`
|
|
@@ -170,4 +189,4 @@ Load only the branch needed now:
|
|
|
170
189
|
- Profile record read/write → `${SKILL_DIR}/references/deploy-record-schema.json` through the single artifact validator
|
|
171
190
|
- declaration read/write → `${SKILL_DIR}/references/deployment-declaration-schema.json` through the single artifact validator
|
|
172
191
|
- existing legacy evidence → `${SKILL_DIR}/references/legacy-migration.md`
|
|
173
|
-
- an explicitly requested real external-resource test rather than an ordinary selected-
|
|
192
|
+
- 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
|
-
##
|
|
30
|
+
## Concrete Controller Input
|
|
31
31
|
|
|
32
|
-
|
|
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
|
-
|
|
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`. 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
|
|
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
|
-
|
|
59
|
+
Return one human action only when identity, target, irreversible or unbounded data effect, or shared ownership still requires a person. 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
|
|
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,45 @@
|
|
|
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
|
+
## Conditional Playbook Loading
|
|
32
|
+
|
|
33
|
+
- project-native controller → `playbook-project-native.md`
|
|
34
|
+
- repository-hosted controller → `playbook-repository-hosted.md`
|
|
35
|
+
- container controller → `playbook-container.md`
|
|
36
|
+
- direct remote/runtime/proxy controller → `playbook-remote-runtime.md`
|
|
37
|
+
- no specialized match → `playbook-generic-fallback.md`
|
|
38
|
+
|
|
39
|
+
Load a second playbook only when selected-command expansion exposes a material child controller that the primary playbook cannot fully establish.
|
|
40
|
+
|
|
41
|
+
## Playbook Contract
|
|
42
|
+
|
|
43
|
+
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.
|
|
44
|
+
|
|
45
|
+
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,26 @@
|
|
|
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. 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
|
+
Attempt one bounded non-interactive probe before requesting authentication. 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.
|
|
10
|
+
|
|
11
|
+
## Build, Transfer, and Runtime
|
|
12
|
+
|
|
13
|
+
1. Observe the project-owned remote directory, current Release, live selector, runtime units, configured health, and exact residual resources without broad host inventory.
|
|
14
|
+
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.
|
|
15
|
+
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.
|
|
16
|
+
4. Check candidate ports and current owners before starting a parallel runtime.
|
|
17
|
+
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.
|
|
18
|
+
6. Verify the candidate, switch live, verify through the live path, then retire exact superseded runtime according to rollback policy.
|
|
19
|
+
|
|
20
|
+
Do not automatically install or replace global packages, users, firewalls, certificates, proxies, or supervisors. Those effects require established project ownership and the applicable Gate.
|
|
21
|
+
|
|
22
|
+
## Repair and Recovery
|
|
23
|
+
|
|
24
|
+
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.
|
|
25
|
+
|
|
26
|
+
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.
|
|
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.
|
|
@@ -55,7 +55,7 @@ Do not pass Secret values in command arguments, print private-key material, star
|
|
|
55
55
|
|
|
56
56
|
## Current → Desired Loop
|
|
57
57
|
|
|
58
|
-
For one selected Profile:
|
|
58
|
+
For one selected environment and its internal Profile record:
|
|
59
59
|
|
|
60
60
|
1. Observe authoritative target state, project revision, automation, live selector, owned resources, persistent/shared dependencies, and existing reusable evidence.
|
|
61
61
|
2. Bind the Profile policy's latest eligible desired release and keep it fixed for this operation.
|
|
@@ -86,9 +86,11 @@ Prefer an evidence-supported candidate/handoff transition:
|
|
|
86
86
|
|
|
87
87
|
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
88
|
|
|
89
|
-
Candidate failure before handoff preserves old live and cleans exact candidate resources.
|
|
89
|
+
Candidate failure before handoff preserves old live and cleans exact candidate resources.
|
|
90
90
|
|
|
91
|
-
|
|
91
|
+
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.
|
|
92
|
+
|
|
93
|
+
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
94
|
|
|
93
95
|
## Data and Dependency Gates
|
|
94
96
|
|
|
@@ -104,11 +106,13 @@ When the project produces an immutable artifact, build it once for one source/to
|
|
|
104
106
|
|
|
105
107
|
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
108
|
|
|
107
|
-
When no artifact mechanism exists, use the current committed revision
|
|
109
|
+
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
110
|
|
|
109
111
|
## Retry, Unknown Outcomes, and Forward Work
|
|
110
112
|
|
|
111
|
-
|
|
113
|
+
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.
|
|
114
|
+
|
|
115
|
+
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
116
|
|
|
113
117
|
After timeout, disconnect, or lost response during a possible write, inspect current target state before replay:
|
|
114
118
|
|
|
@@ -126,9 +130,11 @@ Bound logs by source, purpose, time and/or line count. Prefer omission when reli
|
|
|
126
130
|
|
|
127
131
|
## Post-Success Automation
|
|
128
132
|
|
|
129
|
-
|
|
133
|
+
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.
|
|
134
|
+
|
|
135
|
+
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
136
|
|
|
131
|
-
### Remote
|
|
137
|
+
### Remote Environment
|
|
132
138
|
|
|
133
139
|
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
140
|
|
|
@@ -136,11 +142,11 @@ Separate quick push and pull-request checks from CD. CD should reuse a verified
|
|
|
136
142
|
|
|
137
143
|
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
144
|
|
|
139
|
-
### Local
|
|
145
|
+
### Local Environment
|
|
140
146
|
|
|
141
147
|
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
148
|
|
|
143
|
-
Local automation affects only the selected local
|
|
149
|
+
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
150
|
|
|
145
151
|
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
152
|
|
|
@@ -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
|
|
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
|
|
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
|
|
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`.
|