prizmkit 1.1.166 → 1.1.169
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/dev-pipeline/prizmkit_runtime/runners.py +1 -1
- package/bundled/dev-pipeline/scripts/update-bug-status.py +88 -9
- package/bundled/dev-pipeline/scripts/update-feature-status.py +135 -26
- package/bundled/dev-pipeline/scripts/update-refactor-status.py +102 -4
- package/bundled/dev-pipeline/scripts/utils.py +105 -46
- package/bundled/dev-pipeline/tests/test_auto_skip.py +221 -0
- package/bundled/dev-pipeline/tests/test_python_runner_parity.py +3 -3
- package/bundled/dev-pipeline/tests/test_reset_modes.py +142 -6
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/prizmkit-deploy/SKILL.md +97 -153
- package/bundled/skills/prizmkit-deploy/references/capability-contract.md +59 -110
- package/bundled/skills/prizmkit-deploy/references/deploy-record-schema.json +134 -667
- package/bundled/skills/prizmkit-deploy/references/deployment-declaration-schema.json +78 -191
- package/bundled/skills/prizmkit-deploy/references/legacy-migration.md +50 -69
- package/bundled/skills/prizmkit-deploy/references/policy-and-execution.md +104 -138
- package/bundled/skills/prizmkit-deploy/references/real-resource-test-policy.md +6 -6
- package/bundled/skills/prizmkit-deploy/references/verification-and-recovery.md +76 -115
- package/bundled/skills/prizmkit-deploy/scripts/validate-deploy-artifact.py +462 -173
- package/package.json +1 -1
|
@@ -1,215 +1,159 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: "prizmkit-deploy"
|
|
3
|
-
description: "
|
|
3
|
+
description: "Deploy the latest allowed release to local, remote, test, production, or custom targets through a one-click Profile-based convergence loop, and handle status, health, logs, restart, rollback, takeover, and resume. Use this skill whenever the user asks to deploy, redeploy, 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; only identity, target ambiguity, irreversible data, and shared or unknown-ownership boundaries pause for the user. (project)"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
# PrizmKit Deploy —
|
|
6
|
+
# PrizmKit Deploy — C-Lite AutoDeploy Gateway
|
|
7
7
|
|
|
8
|
-
`/prizmkit-deploy`
|
|
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
|
|
|
10
|
-
|
|
10
|
+
Universal deployment means choosing the shortest truthful path for the observed target. It does not mean inventing unsupported commands or bypassing a human-only boundary.
|
|
11
11
|
|
|
12
12
|
## Scope
|
|
13
13
|
|
|
14
14
|
Use this Skill for:
|
|
15
15
|
|
|
16
|
-
-
|
|
17
|
-
- status, health, bounded logs, restart, stop, rollback, and history;
|
|
18
|
-
-
|
|
19
|
-
-
|
|
16
|
+
- first deployment, redeploy, release promotion, and existing-deployment takeover;
|
|
17
|
+
- status, configured health, bounded logs, restart, stop, rollback, and history;
|
|
18
|
+
- deployment validation, diagnostics, interrupted-operation resume, and decommission/forget intent;
|
|
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
|
|
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.
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
## Semantic Protocol
|
|
26
|
-
|
|
27
|
-
The capability vocabulary is:
|
|
23
|
+
## Invocation and Authority
|
|
28
24
|
|
|
29
25
|
```text
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
26
|
+
/prizmkit-deploy → deploy the selected/default Profile
|
|
27
|
+
/prizmkit-deploy <profile> → deploy that Profile
|
|
28
|
+
/prizmkit-deploy plan → discover and preview without writes
|
|
33
29
|
```
|
|
34
30
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
Operation set:
|
|
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.
|
|
38
32
|
|
|
39
|
-
|
|
40
|
-
deploy, status, health, logs, stop, restart, rollback, history, validate,
|
|
41
|
-
diagnose, takeover, resume, cancel
|
|
42
|
-
```
|
|
33
|
+
Do not ask for a second complete-plan confirmation for those standard actions. Pause only when the next action requires:
|
|
43
34
|
|
|
44
|
-
|
|
35
|
+
1. an identity or authentication action such as login, MFA, or browser approval;
|
|
36
|
+
2. a target choice that current evidence cannot resolve;
|
|
37
|
+
3. an irreversible or insufficiently bounded data effect;
|
|
38
|
+
4. a shared or unknown-ownership resource decision.
|
|
45
39
|
|
|
46
|
-
|
|
40
|
+
A missing rollback mechanism is disclosed but is not a separate confirmation. Privileged or global work outside the Profile's already established target boundary is an authorization/ownership decision and pauses before execution.
|
|
47
41
|
|
|
48
|
-
|
|
42
|
+
## Managed Artifacts
|
|
49
43
|
|
|
50
|
-
|
|
51
|
-
|---|---|---|
|
|
52
|
-
| `.prizmkit/deploy/deploy.json` | Sole local non-sensitive deployment record | Validate with `${SKILL_DIR}/references/deploy-record-schema.json` plus the semantic validator; atomically replace only after the applicable plan confirmation |
|
|
53
|
-
| `prizmkit.deploy.json` | Optional version-controlled non-sensitive declaration | Create or modify only after showing an exact complete file preview and receiving explicit confirmation; validate with `${SKILL_DIR}/references/deployment-declaration-schema.json` plus the semantic validator |
|
|
44
|
+
Prefer project-native deployment configuration. PrizmKit owns only:
|
|
54
45
|
|
|
55
|
-
|
|
46
|
+
| Identity | Role |
|
|
47
|
+
|---|---|
|
|
48
|
+
| `prizmkit.deploy.json` | Optional version-controlled non-sensitive declaration index for Profile hints and policy |
|
|
49
|
+
| `.prizmkit/deploy/profiles/<profile-id>.json` | One local non-sensitive current/result/recovery record per stable Profile |
|
|
56
50
|
|
|
57
|
-
|
|
51
|
+
A Profile record is absent means this is the first PrizmKit-managed deployment for that location. Ask once where to deploy, derive a stable lowercase Profile ID, and then inspect the chosen target. Absence does not prove the target is empty; adopt observed current state instead of creating a duplicate deployment.
|
|
58
52
|
|
|
59
|
-
|
|
53
|
+
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.
|
|
60
54
|
|
|
61
|
-
|
|
55
|
+
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.
|
|
62
56
|
|
|
63
|
-
|
|
64
|
-
2. run `python3 ${SKILL_DIR}/scripts/validate-deploy-artifact.py --kind <record|declaration> <path>` against the exact regular file without following a symlink;
|
|
65
|
-
3. require exit zero and exactly `{"valid":true,"errors":[]}` before using managed fields or replacing/confirming the artifact;
|
|
66
|
-
4. on failure, retain the original/candidate evidence, report only bounded error codes and JSON paths, and return `BLOCKED` before execution or `FAILED` after a confirmed live write as applicable.
|
|
57
|
+
When legacy `.prizmkit/deploy/` evidence exists, read `${SKILL_DIR}/references/legacy-migration.md`. Preserve uncertain evidence and stop legacy writers.
|
|
67
58
|
|
|
68
|
-
|
|
59
|
+
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.
|
|
69
60
|
|
|
70
|
-
|
|
61
|
+
## AutoDeploy Workflow
|
|
71
62
|
|
|
72
|
-
|
|
63
|
+
### 1. Select Profile
|
|
73
64
|
|
|
74
|
-
1.
|
|
75
|
-
2.
|
|
76
|
-
3.
|
|
77
|
-
4.
|
|
78
|
-
5. write the complete candidate to a temporary regular file in the same directory, run its schema and semantic validations, close it, atomically replace the record, then read back and repeat both validations against exact content;
|
|
79
|
-
6. if replacement or read-back validation fails, return `FAILED`, report target-live/local-record-stale when applicable, and rediscover target state before any repair.
|
|
65
|
+
1. Resolve a candidate from the explicitly requested Profile, a valid declared default, or the sole known Profile.
|
|
66
|
+
2. If that candidate has no Profile record, treat the operation as its first PrizmKit deployment and ask once to confirm where to deploy; a declaration hint may propose the location but cannot skip this confirmation.
|
|
67
|
+
3. If no candidate exists, ask once where to deploy and derive the stable Profile identity from that decision.
|
|
68
|
+
4. If multiple Profiles remain possible, ask one target question rather than guessing from environment names.
|
|
80
69
|
|
|
81
|
-
|
|
70
|
+
Different Profiles may operate independently. When the same Profile already has recoverable work, attach to or resume it instead of creating a second candidate.
|
|
82
71
|
|
|
83
|
-
|
|
72
|
+
### 2. Observe Current
|
|
84
73
|
|
|
85
|
-
|
|
74
|
+
Read only the project-native files and target observations needed to establish:
|
|
86
75
|
|
|
87
|
-
|
|
76
|
+
- current source/release and the Profile's latest allowed release;
|
|
77
|
+
- actual target identity, authorization, live selector, runtime units, and configured health;
|
|
78
|
+
- exact project-owned candidates, rollback releases, superseded units, failed attempts, temporary resources, and orphans;
|
|
79
|
+
- persistent/shared dependencies that must not be retired;
|
|
80
|
+
- project-native reports or immutable artifacts that can be reused;
|
|
81
|
+
- selected commands and material child effects through an executable, target-native, or human boundary.
|
|
88
82
|
|
|
89
|
-
|
|
90
|
-
2. Bind the current project root and requested target/profile. Reject traversal into unrelated projects or infrastructure.
|
|
91
|
-
3. Separate read-only discovery from possible writes.
|
|
92
|
-
4. For a real-resource test request, stop ordinary flow and apply `${SKILL_DIR}/references/real-resource-test-policy.md`.
|
|
93
|
-
5. If `deploy.json` exists, run its schema and semantic validations before using any field. Unknown schema versions, malformed objects, unsafe paths/references, incomplete terminal evidence, or Secret-like values block managed writes; do not “repair” by dropping unknown data.
|
|
83
|
+
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.
|
|
94
84
|
|
|
95
|
-
|
|
85
|
+
Read `${SKILL_DIR}/references/capability-contract.md` when selecting or deriving an action.
|
|
96
86
|
|
|
97
|
-
###
|
|
87
|
+
### 3. Bind Desired Release
|
|
98
88
|
|
|
99
|
-
|
|
89
|
+
Fix one desired release for the operation:
|
|
100
90
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
- installed-tool version/help/capability output and current authentication identity, using non-mutating probes;
|
|
105
|
-
- official documentation for the detected language, framework, target, and tool versions when dynamic derivation is needed.
|
|
91
|
+
1. use the Profile policy's latest eligible immutable project artifact when available;
|
|
92
|
+
2. otherwise use the current committed revision;
|
|
93
|
+
3. do not silently include uncommitted workspace content as a release.
|
|
106
94
|
|
|
107
|
-
|
|
95
|
+
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
96
|
|
|
109
|
-
|
|
97
|
+
### 4. Converge
|
|
110
98
|
|
|
111
|
-
|
|
99
|
+
Read `${SKILL_DIR}/references/policy-and-execution.md` before a write or material action. Repeatedly:
|
|
112
100
|
|
|
113
|
-
|
|
101
|
+
1. compute the current → desired difference;
|
|
102
|
+
2. choose the smallest evidence-supported next action;
|
|
103
|
+
3. activate only the conditional Gates implicated by that action;
|
|
104
|
+
4. execute within a finite resource/retry boundary;
|
|
105
|
+
5. observe the result before selecting another action.
|
|
114
106
|
|
|
115
|
-
|
|
116
|
-
- otherwise derive a dynamic plan only from current project evidence, real installed-tool capability, and official documentation;
|
|
117
|
-
- use `manual` when a human must act, and state the exact action plus revalidation;
|
|
118
|
-
- use `unsupported` when evidence or executable capability is absent, and report the gap and safe alternatives.
|
|
107
|
+
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.
|
|
119
108
|
|
|
120
|
-
|
|
109
|
+
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.
|
|
121
110
|
|
|
122
|
-
###
|
|
111
|
+
### 5. Verify and Record
|
|
123
112
|
|
|
124
|
-
|
|
113
|
+
Use the Profile's configured verification when present; otherwise require the minimum target-operation, expected runtime/release identity, intended live state, and bounded startup evidence available for that target. Do not invent a fixed health endpoint. Read `${SKILL_DIR}/references/verification-and-recovery.md` only when those observations cannot directly establish ordinary success or when failure, unknown outcome, rollback, interruption, or resume handling applies.
|
|
125
114
|
|
|
126
|
-
|
|
115
|
+
Success requires the desired release live and the Profile converged. Write one concise result to that Profile record. A record-write problem never authorizes replaying a deployment; report the actual target state and rediscover before record repair.
|
|
127
116
|
|
|
128
|
-
|
|
117
|
+
Terminal status is exactly one of:
|
|
129
118
|
|
|
130
119
|
```text
|
|
131
|
-
|
|
132
|
-
confirmation, execution, verification, failure_handling, idempotency, retry,
|
|
133
|
-
unknown_outcome_inspection
|
|
120
|
+
SUCCEEDED, WAITING_USER, FAILED
|
|
134
121
|
```
|
|
135
122
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
### 5. Apply Confirmation Policy
|
|
139
|
-
|
|
140
|
-
- **Direct:** proven read-only, project-scoped actions.
|
|
141
|
-
- **Complete-plan confirmation:** ordinary reversible writes, including the planned atomic local-record update.
|
|
142
|
-
- **Dedicated confirmation:** project/source file creation or modification; privileged/global or compatibility-sensitive install/upgrade; destructive or irreversible migration; shared infrastructure; plan expansion; replay after an unknown write outcome; or deployment without reliable rollback.
|
|
143
|
-
|
|
144
|
-
A missing rollback mechanism does not automatically block deployment. Continue only after an exact dedicated risk-acceptance confirmation that identifies live-state risk and manual recovery. Store the fact and scope of confirmation, never credentials or unrelated conversation.
|
|
145
|
-
|
|
146
|
-
Any changed target, command, argument, input, effect, scope, evidence assumption, or risk invalidates confirmation. Compile and preview a new plan.
|
|
147
|
-
|
|
148
|
-
### 6. Execute with Progress and Human Checkpoints
|
|
149
|
-
|
|
150
|
-
Execute the confirmed plan in order. Before each step, recheck preconditions and confirmation validity. Report the capability, step state, and bounded evidence; do not promise a universal duration.
|
|
123
|
+
`WAITING_USER` is resumable and names one exact non-sensitive action. Use `FAILED` only when no safe continuation exists or the user stops the operation.
|
|
151
124
|
|
|
152
|
-
|
|
153
|
-
- Only proven read-only or idempotent operations may use the plan's bounded retry.
|
|
154
|
-
- On timeout/disconnect after a possible write, mark the outcome unknown and inspect before replay.
|
|
155
|
-
- Analyze every database migration for reversibility, locking/downtime, data impact, backup/restore evidence, sequencing, and recovery conditions.
|
|
156
|
-
- Bound logs by time and/or line count and redact before display or persistence.
|
|
125
|
+
### 6. Offer Automation
|
|
157
126
|
|
|
158
|
-
|
|
127
|
+
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, ask whether the user wants to avoid future full manual deployment runs:
|
|
159
128
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
4. after the user acts, revalidate target identity, authentication/authorization, capability evidence, and the expected postcondition;
|
|
164
|
-
5. resume only if the immutable plan still matches; otherwise compile a new plan.
|
|
165
|
-
|
|
166
|
-
`cancel` stops future steps, performs only already-confirmed safe cleanup, records residual resources, and returns `CANCELLED`.
|
|
167
|
-
|
|
168
|
-
### 7. Verify, Recover, and Report
|
|
169
|
-
|
|
170
|
-
Read `${SKILL_DIR}/references/verification-and-recovery.md` before deciding an outcome. Check every applicable layer:
|
|
171
|
-
|
|
172
|
-
1. command or target-control result;
|
|
173
|
-
2. process, service, container, or release state;
|
|
174
|
-
3. configured health boundary;
|
|
175
|
-
4. external URL;
|
|
176
|
-
5. bounded startup logs.
|
|
177
|
-
|
|
178
|
-
Each layer is `PASSED`, `FAILED`, `INACCESSIBLE`, or `NOT_APPLICABLE`. Inaccessible and inapplicable are not passes. A required failed or inaccessible layer prevents `SUCCEEDED`; command exit alone is never sufficient.
|
|
179
|
-
|
|
180
|
-
On failure or interruption, observe current state before action. Offer rollback only when the rollback mechanism and target release are verified. Without verified rollback, report live state, residual resources, and manual recovery explicitly.
|
|
181
|
-
|
|
182
|
-
Terminal status is exactly one of:
|
|
183
|
-
|
|
184
|
-
```text
|
|
185
|
-
SUCCEEDED, FAILED, BLOCKED, WAITING_USER, CANCELLED
|
|
186
|
-
```
|
|
129
|
+
- 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;
|
|
130
|
+
- for another remote repository, offer only an equivalent supported by current project/host evidence;
|
|
131
|
+
- for a local Profile, offer project-native watch/hot reload, incremental restart, container sync/watch, or a lightweight commit-triggered local deploy.
|
|
187
132
|
|
|
188
|
-
|
|
133
|
+
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.
|
|
189
134
|
|
|
190
|
-
|
|
135
|
+
## Output
|
|
191
136
|
|
|
192
|
-
|
|
137
|
+
Report:
|
|
193
138
|
|
|
194
139
|
- terminal status and operation;
|
|
195
|
-
- target
|
|
196
|
-
-
|
|
197
|
-
- rollback availability;
|
|
198
|
-
-
|
|
199
|
-
-
|
|
200
|
-
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
-
|
|
210
|
-
-
|
|
211
|
-
-
|
|
212
|
-
-
|
|
213
|
-
-
|
|
214
|
-
-
|
|
215
|
-
- any proposed external-resource test → `${SKILL_DIR}/references/real-resource-test-policy.md`
|
|
140
|
+
- selected Profile, target reference, desired and actual live release;
|
|
141
|
+
- concise verification observations and residual resources;
|
|
142
|
+
- rollback availability without treating it as required approval;
|
|
143
|
+
- Profile record result;
|
|
144
|
+
- one exact recovery action for `WAITING_USER`, or the evidence-backed failure reason;
|
|
145
|
+
- optional automation offer only after successful convergence.
|
|
146
|
+
|
|
147
|
+
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.
|
|
148
|
+
|
|
149
|
+
## Conditional Reference Loading
|
|
150
|
+
|
|
151
|
+
Load only the branch needed now:
|
|
152
|
+
|
|
153
|
+
- action derivation or evidence conflict → `${SKILL_DIR}/references/capability-contract.md`
|
|
154
|
+
- write, material work, migration, redeploy, dependency, promotion, or automation setup → `${SKILL_DIR}/references/policy-and-execution.md`
|
|
155
|
+
- success cannot be established directly, or failure, unknown outcome, rollback, interruption, or resume applies → `${SKILL_DIR}/references/verification-and-recovery.md`
|
|
156
|
+
- Profile record read/write → `${SKILL_DIR}/references/deploy-record-schema.json` through the single artifact validator
|
|
157
|
+
- declaration read/write → `${SKILL_DIR}/references/deployment-declaration-schema.json` through the single artifact validator
|
|
158
|
+
- existing legacy evidence → `${SKILL_DIR}/references/legacy-migration.md`
|
|
159
|
+
- an explicitly requested real external-resource test rather than an ordinary selected-Profile deployment → `${SKILL_DIR}/references/real-resource-test-policy.md`
|
|
@@ -1,137 +1,86 @@
|
|
|
1
1
|
# Deployment Capability Contract
|
|
2
2
|
|
|
3
|
-
Use this
|
|
3
|
+
Use this reference when current evidence must be converted into one deploy or operations action. Capability names express semantic outcomes; product, provider, tool, language, framework, controller, and operating-system names remain evidence only.
|
|
4
4
|
|
|
5
5
|
## Capability Vocabulary
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
| `build` | Transform source into a verified build output using project-native instructions. |
|
|
13
|
-
| `package` | Produce or select a transferable/releasable artifact with identity and integrity evidence. |
|
|
14
|
-
| `transfer` | Move an artifact or source input across the required boundary without assuming compatibility of dependency directories. |
|
|
15
|
-
| `configure` | Apply project-scoped runtime, routing, environment, or target configuration. |
|
|
16
|
-
| `migrate` | Apply an analyzed data/schema/state transition. |
|
|
17
|
-
| `release` | Create, select, promote, or activate an identifiable release. |
|
|
18
|
-
| `start` | Start the project-owned runtime unit. |
|
|
19
|
-
| `stop` | Stop the project-owned runtime unit. |
|
|
20
|
-
| `restart` | Restart the project-owned runtime unit and verify recovery. |
|
|
21
|
-
| `rollback` | Restore a verified prior release/configuration/data state. |
|
|
22
|
-
| `status` | Observe current release and runtime state. |
|
|
23
|
-
| `health` | Evaluate the configured health boundary. |
|
|
24
|
-
| `logs` | Read bounded project-owned operational output. |
|
|
25
|
-
| `history` | Read concise local and target-native operation/release evidence. |
|
|
26
|
-
| `validate` | Check configuration, prerequisites, authorization, and plan consistency without deployment writes. |
|
|
27
|
-
| `diagnose` | Gather bounded project-scoped evidence for a deployment or runtime problem. |
|
|
28
|
-
| `takeover` | Discover ownership, coexistence, backup, and rollback boundaries before adopting an existing deployment. |
|
|
29
|
-
|
|
30
|
-
Select only capabilities applicable to the requested operation, but never omit a prerequisite merely because automation is unavailable.
|
|
31
|
-
|
|
32
|
-
## Availability
|
|
33
|
-
|
|
34
|
-
Exactly one value applies to each selected capability:
|
|
35
|
-
|
|
36
|
-
| Availability | Required basis | Permitted behavior |
|
|
37
|
-
|---|---|---|
|
|
38
|
-
| `verified` | A maintained recipe plus a complete current evidence fingerprint matching all recipe constraints. | Compile the recipe's actions, still applying current policy, confirmation, and verification. |
|
|
39
|
-
| `dynamic` | Current project evidence, actual installed-tool capability, and applicable official documentation agree on a safe action. | Derive explicit actions and pass them through the same policy gate as a verified recipe. |
|
|
40
|
-
| `manual` | Automation ends at a user-controlled, credential, approval, UI, physical, or unavailable execution boundary. | State the exact user action, expected postcondition, and revalidation; return `WAITING_USER` when reached. |
|
|
41
|
-
| `unsupported` | Required evidence, access, compatible capability, or a safe execution method is absent. | Report the gap and safe alternatives; do not fabricate commands, mark completion, or promise support. |
|
|
42
|
-
|
|
43
|
-
`verified` describes evidence, not low risk. `dynamic` does not authorize experimentation. `manual` does not mean complete. An operation with a required `unsupported` capability is `BLOCKED` unless the user chooses an in-scope alternative plan.
|
|
44
|
-
|
|
45
|
-
## Descriptor
|
|
46
|
-
|
|
47
|
-
Every selected capability descriptor contains all fields below. Empty lists are explicit; no field is omitted.
|
|
7
|
+
```text
|
|
8
|
+
discover, connect, authenticate, build, package, transfer, configure, migrate,
|
|
9
|
+
release, start, stop, restart, rollback, status, health, logs, history, validate,
|
|
10
|
+
diagnose, takeover
|
|
11
|
+
```
|
|
48
12
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
| `risk` | `read_only`, `reversible_write`, `high_impact`, or `destructive`, with a plain-language reason. |
|
|
58
|
-
| `confirmation` | `none`, `complete_plan`, or one or more dedicated confirmation reasons. |
|
|
59
|
-
| `execution` | Exact executable plus argument array, target-native action, or human action. No incomplete shell fragment. |
|
|
60
|
-
| `verification` | Observable postconditions and whether each is required or optional. |
|
|
61
|
-
| `failure_recovery` | Stop condition, safe cleanup, inspection, rollback eligibility, and manual recovery when rollback is absent. |
|
|
62
|
-
|
|
63
|
-
Execution stays data-shaped where possible: executable and arguments are separate, the working directory is project-relative, and Secret material is injected by the user/target-owned system. Never interpolate an untrusted value into an opaque shell command.
|
|
64
|
-
|
|
65
|
-
## Evidence Precedence and Conflict
|
|
66
|
-
|
|
67
|
-
Use the strongest current evidence, in this order:
|
|
68
|
-
|
|
69
|
-
1. directly observed project-native configuration and target state;
|
|
70
|
-
2. real installed-tool version/help/capability/authentication output;
|
|
13
|
+
Select only the capabilities required to close the current → desired difference. An unavailable prerequisite stays visible, but an unrelated capability does not need an empty descriptor.
|
|
14
|
+
|
|
15
|
+
## Evidence Precedence
|
|
16
|
+
|
|
17
|
+
Use current evidence in this order:
|
|
18
|
+
|
|
19
|
+
1. directly observed project-native configuration and target/control-plane state;
|
|
20
|
+
2. actual installed-tool capability, version, help, and authentication identity;
|
|
71
21
|
3. official documentation applicable to the observed version and target;
|
|
72
|
-
4.
|
|
73
|
-
5. the
|
|
74
|
-
6. user
|
|
22
|
+
4. a valid optional deployment declaration;
|
|
23
|
+
5. the selected valid Profile record and preserved legacy evidence;
|
|
24
|
+
6. user statements, labeled as supplied rather than observed.
|
|
75
25
|
|
|
76
|
-
Lower evidence may identify what to inspect but
|
|
26
|
+
Lower evidence may identify what to inspect but cannot override current direct observation. Re-observe when project revision, target identity, tool version, authentication identity, native configuration, selected action, release input, live inventory, health boundary, or retention policy changes.
|
|
77
27
|
|
|
78
|
-
|
|
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
|
+
|
|
30
|
+
## Base Action Contract
|
|
31
|
+
|
|
32
|
+
Every selected automatic or human action contains only these base facts:
|
|
33
|
+
|
|
34
|
+
| Field | Contract |
|
|
35
|
+
|---|---|
|
|
36
|
+
| `purpose` | The current → desired difference this action closes. |
|
|
37
|
+
| `evidence` | Bounded current observations, origins, freshness, and conflicts; no Secret values. |
|
|
38
|
+
| `effects` | Project, target, traffic, data, credential, cost, and residual-resource effects that actually apply. |
|
|
39
|
+
| `action` | Complete executable plus arguments, target-native action, or one exact human action. |
|
|
40
|
+
| `verification` | Observable required and optional postconditions for this action. |
|
|
79
41
|
|
|
80
|
-
|
|
42
|
+
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.
|
|
81
43
|
|
|
82
|
-
|
|
44
|
+
An action is automatic when current evidence proves its executable shape, target, effects, ownership, bounded resource behavior, and verification inside the standard deployment envelope. When a person must authenticate, choose a target, decide an irreversible data effect, or resolve shared ownership, represent one exact human action and expected postcondition. When no safe action can be established, report the missing evidence or unsupported capability instead of fabricating a command.
|
|
83
45
|
|
|
84
|
-
|
|
85
|
-
- artifact format and controller/target compatibility;
|
|
86
|
-
- installed tool/runtime and relevant feature versions;
|
|
87
|
-
- target type, identity, transport, and authorization boundary;
|
|
88
|
-
- configuration ownership and actual connection/service ports;
|
|
89
|
-
- health boundary and required verification layers;
|
|
90
|
-
- rollback mechanism and release identity semantics;
|
|
91
|
-
- migration and persistent-data assumptions;
|
|
92
|
-
- declared effects and confirmation class.
|
|
46
|
+
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.
|
|
93
47
|
|
|
94
|
-
|
|
48
|
+
## Conditional Gates
|
|
95
49
|
|
|
96
|
-
|
|
50
|
+
Attach a Gate only when its condition applies:
|
|
97
51
|
|
|
98
|
-
|
|
52
|
+
- **Resource Gate:** material compute, memory, disk/cache, network, provider cost, temporary resources, or repetition.
|
|
53
|
+
- **Supersession Gate:** an existing live/candidate/rollback deployment may be replaced, retained, or retired.
|
|
54
|
+
- **Data Gate:** migration or another persistent-data effect occurs.
|
|
55
|
+
- **Shared Resource Gate:** another workload may consume the resource or ownership is uncertain.
|
|
56
|
+
- **Human Checkpoint:** identity, authentication, target choice, irreversible data, or shared ownership requires the user.
|
|
57
|
+
- **Unknown Outcome Gate:** a write may have happened but its result is not proven.
|
|
99
58
|
|
|
100
|
-
|
|
59
|
+
The applicable Gate owns its additional facts and policy. Do not add supersession to status/log actions, data analysis to a build without data effects, or a human checkpoint to an ordinary authorized write.
|
|
101
60
|
|
|
102
|
-
|
|
103
|
-
2. **Real capability evidence:** the installed tool or reachable target exposes the required function and applicable version; a filename or remembered CLI is insufficient.
|
|
104
|
-
3. **Official documentation:** documentation for the observed language/framework/target/tool version supports the exact action and semantics.
|
|
61
|
+
## Selected Command Expansion
|
|
105
62
|
|
|
106
|
-
|
|
63
|
+
Inspect only the command/action selected for execution and its material project-native children. Expand through manifest aliases, task runners, workflows, and scripts until each material branch reaches a known executable, target-native action, or human boundary. Record hidden repetition, parallelism, downloads, caches, generated/temporary outputs, provider calls, cleanup, and interruption effects.
|
|
107
64
|
|
|
108
|
-
|
|
109
|
-
- classify every effect and confirmation boundary;
|
|
110
|
-
- use actual ports/endpoints and target identity;
|
|
111
|
-
- identify idempotency and unknown-outcome inspection;
|
|
112
|
-
- pass the step through the same immutable plan policy as a verified recipe;
|
|
113
|
-
- mark any remaining human boundary `manual` rather than hiding it inside a command.
|
|
65
|
+
Do not run an opaque wrapper to learn what it does. If a material child remains opaque, choose a smaller known action, ask for the exact human action, or report that no safe automatic action is available.
|
|
114
66
|
|
|
115
|
-
|
|
67
|
+
Read-only status, health, history, or bounded logs do not require expansion of unrelated build/release workflows.
|
|
116
68
|
|
|
117
|
-
##
|
|
69
|
+
## Release and Profile Evidence
|
|
118
70
|
|
|
119
|
-
|
|
120
|
-
- `unsupported` → another state only after new evidence is observed; user optimism alone is not evidence.
|
|
121
|
-
- `verified` → `dynamic`, `manual`, or `unsupported` whenever its fingerprint no longer matches.
|
|
122
|
-
- Any state → blocked execution when preconditions, confirmation, or required verification cannot be established.
|
|
71
|
+
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; after the user identifies the target, inspect it before assuming a first physical deployment.
|
|
123
72
|
|
|
124
|
-
|
|
73
|
+
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.
|
|
125
74
|
|
|
126
|
-
##
|
|
75
|
+
## Intent Starting Points
|
|
127
76
|
|
|
128
|
-
|
|
77
|
+
- **Deploy/redeploy:** discover current, bind desired, validate prerequisites, then select only the actions needed to converge release, runtime, health, retention, and cleanup.
|
|
78
|
+
- **Status/health/logs/history:** use project-scoped read-only observations and no local record write.
|
|
79
|
+
- **Restart/stop/rollback:** observe the exact current project-owned unit/release, perform the selected action, and verify the intended live/offline state.
|
|
80
|
+
- **Validate/diagnose:** run negligible observations directly; a material producer or invasive repair enters the deployment policy.
|
|
81
|
+
- **Takeover/resume:** rediscover ownership and actual effects before selecting a write; never reconstruct execution from a history summary.
|
|
82
|
+
- **Decommission/forget:** decommission changes exact target resources; forget removes only local management evidence. Never infer one from the other.
|
|
129
83
|
|
|
130
|
-
|
|
131
|
-
- `status`, `health`, `logs`, `history`: discover and connect/authenticate only when needed; remain read-only.
|
|
132
|
-
- `restart`, `stop`, `rollback`: discover current live/release state first, mutate only the current project's runtime/release, then verify health/live state.
|
|
133
|
-
- `validate`, `diagnose`: read-only by default; any repair or invasive probe becomes a separately confirmed mutating plan.
|
|
134
|
-
- `takeover`: discover ownership and conflicts, inspect backup/rollback/coexistence boundaries, and require a new plan before any adoption write.
|
|
135
|
-
- `resume`: rediscover all evidence referenced by the stored plan before continuing.
|
|
84
|
+
## Conflict Outcome
|
|
136
85
|
|
|
137
|
-
|
|
86
|
+
A conflict affecting project/target identity, authorization, selected command, data, live selector, health, release identity, or ownership prevents that action. Resolve it through a smaller read-only observation or one exact `WAITING_USER` action. Unrelated incomplete evidence does not block an otherwise proven action.
|