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.
@@ -1,215 +1,159 @@
1
1
  ---
2
2
  name: "prizmkit-deploy"
3
- description: "Capability-driven deployment and online-operations gateway for arbitrary projects and targets. Discovers project-native evidence and real tool capabilities, classifies semantic deployment capabilities as verified, dynamic, manual, or unsupported, then compiles a risk-gated plan or collaborates at human checkpoints. Handles deploy, status, health, bounded logs, restart, rollback, history, validate, diagnose, takeover, and interrupted-session resume without promising unattended automation. If the user says only 'ship it', clarify commit versus deploy first. (project)"
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 — Capability-Driven Gateway
6
+ # PrizmKit Deploy — C-Lite AutoDeploy Gateway
7
7
 
8
- `/prizmkit-deploy` assesses and collaborates on deployment and online operations for the current project. It does not route by language, framework, controller, provider, tool, or operating-system name. Those names are evidence only.
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
- **Universal means truthful assessment and collaboration, not guaranteed unattended automation.** A target can require login, MFA, browser approval, a manual action, or a capability the current environment cannot perform.
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
- - deploy and release requests;
17
- - status, health, bounded logs, restart, stop, rollback, and history;
18
- - configuration validation, diagnostics, and existing-deployment takeover;
19
- - authentication checkpoints and interruption recovery related to the current deployment.
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 current project and its necessary deployment dependencies. Assume one operator. Make no concurrent-write or locking guarantee.
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
- If the request is only “ship it,” clarify commit versus deployment. In a non-interactive run where that ambiguity cannot be resolved, return `BLOCKED`; never guess.
24
-
25
- ## Semantic Protocol
26
-
27
- The capability vocabulary is:
23
+ ## Invocation and Authority
28
24
 
29
25
  ```text
30
- discover, connect, authenticate, build, package, transfer, configure, migrate,
31
- release, start, stop, restart, rollback, status, health, logs, history, validate,
32
- diagnose, takeover
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
- Every applicable capability is `verified`, `dynamic`, `manual`, or `unsupported` and has evidence, preconditions, inputs, effects, risk, confirmation, execution, verification, and failure recovery. Read `${SKILL_DIR}/references/capability-contract.md` before classifying capabilities or deriving a plan.
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
- ```text
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
- Authentication, login, MFA, browser approval, and other user actions are checkpoints inside an operation, not target routes.
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
- ## Managed Artifact Boundary
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
- Prefer existing project-native deployment configuration. PrizmKit owns at most these two new artifacts:
42
+ ## Managed Artifacts
49
43
 
50
- | Identity | Role | Write rule |
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
- Do not create a PrizmKit state, config, template, document, script, pending-input file, metadata file, or history file per language, framework, target, capability, phase, release, or event. Do not create local Secret storage. Secret values stay in user- or target-owned Secret systems; the local record and optional declaration store references and presence only.
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
- The optional declaration is advisory evidence. It never proves that a tool is installed, authentication is current, the target is authorized, a command is safe, or deployment is approved.
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
- ### Managed Artifact Validation
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
- Before trusting an existing managed artifact or accepting a complete write candidate, require both schema validation and semantic validation:
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
- 1. validate the complete object with its matching Draft 2020-12 schema;
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
- The shipped script is a read-only semantic companion, not a schema replacement. It checks duplicate keys, canonical project-relative paths, profile identity/references, the exact verification-layer set, success consistency, and forbidden sensitive/raw-output field shapes without displaying values. If either validation capability is unavailable, do not guess, drop unknown data, or accept the managed artifact.
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
- ### Sole-Record Update Policy
61
+ ## AutoDeploy Workflow
71
62
 
72
- For every confirmed `deploy.json` write:
63
+ ### 1. Select Profile
73
64
 
74
- 1. read and validate the existing record without following a symlink or dropping unknown data;
75
- 2. build one complete candidate, preserving fields not intentionally changed by the confirmed plan;
76
- 3. update `current` only from verified live/release/health/rollback evidence, set the complete `latest_result`, append one concise redacted `history` summary, retain only the newest 50 summaries, and set or clear minimal `recovery` according to the terminal state;
77
- 4. reject Secret-like values, raw command output, full logs, duplicate profile identities, and dangling profile references;
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
- Trimming the bounded new-record history is part of this disclosed update policy; it never deletes or alters legacy evidence. This atomic replacement contract assumes one operator and makes no concurrent-write claim.
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
- When an existing `.prizmkit/deploy/` directory contains legacy artifacts, read `${SKILL_DIR}/references/legacy-migration.md` before any managed write. Preserve uncertain evidence and stop all legacy write patterns.
72
+ ### 2. Observe Current
84
73
 
85
- ## Workflow
74
+ Read only the project-native files and target observations needed to establish:
86
75
 
87
- ### 1. Normalize Intent and Boundary
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
- 1. Resolve one operation from the operation set.
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
- No-argument behavior: assess a deploy if target evidence exists; otherwise perform read-only discovery and return `WAITING_USER` with the missing non-secret target decision. A no-argument invocation is not plan confirmation.
85
+ Read `${SKILL_DIR}/references/capability-contract.md` when selecting or deriving an action.
96
86
 
97
- ### 2. Discover Evidence Read-Only
87
+ ### 3. Bind Desired Release
98
88
 
99
- Read only what is needed:
89
+ Fix one desired release for the operation:
100
90
 
101
- - project-native manifests, build/release/runtime configuration, health definitions, deployment files, and source references needed to identify commands and ports;
102
- - the sole local record and optional declaration, if present and valid;
103
- - target facts supplied by the user or observed through proven read-only inspection;
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
- Record evidence origin, observation, freshness, and whether it was read directly or user-supplied. A filename or target label alone is not proof. Respect actual connection and service ports; never substitute a conventional or fixed port.
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
- Do not expose Secret values discovered in files, command output, environment, URLs, headers, or logs. Retain only a Secret name/reference and presence state.
97
+ ### 4. Converge
110
98
 
111
- ### 3. Build the Capability Matrix
99
+ Read `${SKILL_DIR}/references/policy-and-execution.md` before a write or material action. Repeatedly:
112
100
 
113
- Use the capability contract to classify every capability required by the operation:
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
- - prefer a verified recipe only when its complete evidence fingerprint still matches;
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
- Dynamic is not a weaker safety mode. Dynamic, verified, and mixed plans pass the same policy and confirmation gates. Never turn guidance copied from memory or an unofficial example into executable evidence.
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
- ### 4. Choose Read-Only Execution or Compile a Plan
111
+ ### 5. Verify and Record
123
112
 
124
- Read-only, project-scoped discovery, status, health, bounded logs, history, validation, and diagnostics may execute directly when every selected command is proven read-only. Report their evidence without mutating the target or local record.
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
- A diagnostic command that may write, restart, install, repair, rotate, prune, migrate, or change authentication is not read-only and must enter the plan.
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
- For deploy or any mutating operation, read `${SKILL_DIR}/references/policy-and-execution.md` and compile the complete immutable plan. Every step must contain:
117
+ Terminal status is exactly one of:
129
118
 
130
119
  ```text
131
- capability, availability, evidence, preconditions, inputs, effects, risk,
132
- confirmation, execution, verification, failure_handling, idempotency, retry,
133
- unknown_outcome_inspection
120
+ SUCCEEDED, WAITING_USER, FAILED
134
121
  ```
135
122
 
136
- Bind the plan to project root, target identity, release input, ordered steps, command arguments/actions, effects, and risk. Show the complete plan before requesting confirmation. A request to deploy is not itself confirmation of the compiled plan; silence, an old approval, or approval of a different plan is not confirmation.
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
- - Never silently install, upgrade, overwrite, delete, expand scope, or replay a write.
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
- For login, MFA, browser approval, or manual action:
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
- 1. stop before dependent execution;
161
- 2. report `WAITING_USER` and the exact non-secret action;
162
- 3. store only the plan digest, last proven step, minimal confirmation receipts, pending checkpoint, and bounded observations in `deploy.json` when that write was confirmed;
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
- ## Secret and Output Rules
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
- Before display or persistence, redact credentials in URLs, authorization headers, tokens, keys, cookies, connection strings, environment assignments, and user-identified sensitive patterns. Prefer omission over masking when context is unnecessary. Do not persist raw command output or full logs.
135
+ ## Output
191
136
 
192
- The final result includes:
137
+ Report:
193
138
 
194
139
  - terminal status and operation;
195
- - target/profile and live state;
196
- - release identity, if established;
197
- - rollback availability;
198
- - every verification layer and evidence boundary;
199
- - residual resources and partial effects;
200
- - local-record update result;
201
- - recovery guidance and relevant next operations.
202
-
203
- If the live change succeeded but a required health check or local-record update failed, return `FAILED` and describe the actual live state. Never label partial completion as success.
204
-
205
- ## Reference Loading
206
-
207
- Load only what the current operation needs:
208
-
209
- - capability assessment or dynamic derivation → `${SKILL_DIR}/references/capability-contract.md`
210
- - local record read/write → `${SKILL_DIR}/references/deploy-record-schema.json` and `${SKILL_DIR}/scripts/validate-deploy-artifact.py`
211
- - optional declaration preview/write → `${SKILL_DIR}/references/deployment-declaration-schema.json` and `${SKILL_DIR}/scripts/validate-deploy-artifact.py`
212
- - first use with legacy evidence → `${SKILL_DIR}/references/legacy-migration.md`
213
- - any mutating plan → `${SKILL_DIR}/references/policy-and-execution.md`
214
- - verification, failure, rollback, interruption, or resume → `${SKILL_DIR}/references/verification-and-recovery.md`
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 contract to convert current project and target evidence into semantic deployment capabilities. Capability names are protocol identifiers; product, language, framework, controller, tool, provider, and operating-system names are not.
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
- | Capability | Semantic outcome |
8
- |---|---|
9
- | `discover` | Establish project, target, release, configuration, dependency, and health evidence. |
10
- | `connect` | Reach the intended target through an identified, authorized transport or control boundary. |
11
- | `authenticate` | Establish and revalidate the operator identity and authorization needed by later actions. |
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
- | Field | Contract |
50
- |---|---|
51
- | `name` | One capability from the vocabulary. |
52
- | `availability` | `verified`, `dynamic`, `manual`, or `unsupported`. |
53
- | `evidence` | Bounded observations with origin, observed fact, observation method, freshness, and relevance. No Secret values. |
54
- | `preconditions` | Conditions that must be true immediately before execution. |
55
- | `inputs` | Non-sensitive values/references bound into the action; Secret references identify an external source, never a value. |
56
- | `effects` | Project, target, data, traffic, cost, credential, and residual-resource effects. |
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. the validated optional project declaration;
73
- 5. the validated local record and preserved legacy evidence;
74
- 6. user-supplied statements, labeled as such.
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 does not override a current direct observation. On conflict, show the conflicting facts and use the safer state. A conflict affecting identity, effects, authorization, command shape, migration, health, or rollback blocks execution until resolved.
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
- Evidence expires when the target identity, project revision, tool/runtime version, authentication identity, native configuration, health boundary, or release input changes. Re-observe affected descriptors before execution or resume.
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
- ## Verified Recipe Gate
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
- A recipe is eligible only when all of these match current evidence:
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
- - project-native build/start/release interface and working directory;
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
- The recipe records the evidence fingerprint used for the match. Partial matches, inferred defaults, stale versions, or a matching product name are not sufficient. When any required fingerprint field is missing or mismatched, reject the recipe and consider `dynamic`, `manual`, or `unsupported`.
48
+ ## Conditional Gates
95
49
 
96
- A verified recipe never bypasses confirmation, Secret handling, data analysis, unknown-outcome inspection, or layered verification.
50
+ Attach a Gate only when its condition applies:
97
51
 
98
- ## Dynamic Derivation Gate
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
- A dynamic capability is permitted only when all three evidence sources are present and consistent:
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
- 1. **Current project evidence:** native configuration or source establishes the intended command/action and inputs.
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
- Then:
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
- - construct a complete descriptor;
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
- If official documentation cannot be accessed, do not improvise a write. Read-only assessment may continue; the write is `manual` or `unsupported` with the missing evidence stated.
67
+ Read-only status, health, history, or bounded logs do not require expansion of unrelated build/release workflows.
116
68
 
117
- ## Availability Transitions
69
+ ## Release and Profile Evidence
118
70
 
119
- - `manual` → `verified` or `dynamic` only after the user action is complete and its postcondition, identity, and authorization are revalidated.
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
- Record transition evidence in the operation result, not as an unbounded transcript.
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
- ## Capability Dependencies by Intent
75
+ ## Intent Starting Points
127
76
 
128
- These are semantic starting points, not fixed routes:
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
- - `deploy`: always `discover`, `validate`, `release`, and `health`; add connect/authenticate/build/package/transfer/configure/migrate/start/stop/rollback according to evidence and effects.
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
- Required unavailable dependencies stay visible in the matrix. Do not collapse a partially assessable operation into a generic fallback success.
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.