prizmkit 1.1.159 → 1.1.160

package/bundled/skills/prizmkit-deploy/references/deployment-declaration-schema.json

@@ -0,0 +1,291 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://prizmkit.dev/schemas/deployment-declaration.schema.json",
+  "title": "Optional PrizmKit Deployment Declaration",
+  "description": "Complete non-sensitive schema for optional prizmkit.deploy.json. The file is advisory evidence, not execution authorization. Secret values are prohibited.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "project_root",
+    "native_config_files",
+    "profile_hints",
+    "secret_references",
+    "commands",
+    "capability_hints"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "project_root": {
+      "const": "."
+    },
+    "native_config_files": {
+      "type": "array",
+      "maxItems": 50,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/projectRelativePath"
+      }
+    },
+    "profile_hints": {
+      "type": "array",
+      "maxItems": 20,
+      "items": {
+        "$ref": "#/$defs/profileHint"
+      }
+    },
+    "secret_references": {
+      "type": "array",
+      "maxItems": 100,
+      "items": {
+        "$ref": "#/$defs/secretReference"
+      }
+    },
+    "commands": {
+      "type": "array",
+      "maxItems": 100,
+      "items": {
+        "$ref": "#/$defs/command"
+      }
+    },
+    "capability_hints": {
+      "type": "array",
+      "maxItems": 100,
+      "items": {
+        "$ref": "#/$defs/capabilityHint"
+      }
+    }
+  },
+  "$defs": {
+    "capabilityName": {
+      "enum": [
+        "discover",
+        "connect",
+        "authenticate",
+        "build",
+        "package",
+        "transfer",
+        "configure",
+        "migrate",
+        "release",
+        "start",
+        "stop",
+        "restart",
+        "rollback",
+        "status",
+        "health",
+        "logs",
+        "history",
+        "validate",
+        "diagnose",
+        "takeover"
+      ]
+    },
+    "projectRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(?!/)(?![A-Za-z]:)(?!.*\\\\)(?!.*//)(?!.*\/$)(?!\\.{1,2}(?:/|$))(?!.*(?:/)\\.{1,2}(?:/|$))[^\\u0000-\\u001f\\u007f-\\u009f\\ud800-\\udfff]+$"
+    },
+    "projectRelativeDirectory": {
+      "oneOf": [
+        {
+          "const": "."
+        },
+        {
+          "$ref": "#/$defs/projectRelativePath"
+        }
+      ]
+    },
+    "profileHint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "environment",
+        "target_ref",
+        "endpoint_ref",
+        "actual_ports",
+        "health_boundary"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+        },
+        "environment": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "target_ref": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "endpoint_ref": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 512
+        },
+        "actual_ports": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535
+          }
+        },
+        "health_boundary": {
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "$ref": "#/$defs/healthCheck"
+          }
+        }
+      }
+    },
+    "healthCheck": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "kind",
+        "target_ref",
+        "expected",
+        "required"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "kind": {
+          "enum": [
+            "command",
+            "service_state",
+            "network",
+            "application",
+            "target_native"
+          ]
+        },
+        "target_ref": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "expected": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "required": {
+          "type": "boolean"
+        }
+      }
+    },
+    "secretReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Name and external source reference only; never include a Secret value, hash, token, password, key, cookie, header, or connection string.",
+      "required": [
+        "name",
+        "source_ref",
+        "required"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[A-Za-z_][A-Za-z0-9_.-]{0,127}$"
+        },
+        "source_ref": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "required": {
+          "type": "boolean"
+        }
+      }
+    },
+    "command": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "capability",
+        "executable",
+        "args",
+        "working_directory",
+        "source"
+      ],
+      "properties": {
+        "capability": {
+          "$ref": "#/$defs/capabilityName"
+        },
+        "executable": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "args": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "type": "string",
+            "maxLength": 1024
+          }
+        },
+        "working_directory": {
+          "$ref": "#/$defs/projectRelativeDirectory"
+        },
+        "source": {
+          "enum": [
+            "project_native",
+            "user_confirmed"
+          ]
+        }
+      }
+    },
+    "capabilityHint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "capability",
+        "evidence_files",
+        "manual_checkpoint",
+        "notes"
+      ],
+      "properties": {
+        "capability": {
+          "$ref": "#/$defs/capabilityName"
+        },
+        "evidence_files": {
+          "type": "array",
+          "maxItems": 20,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/projectRelativePath"
+          }
+        },
+        "manual_checkpoint": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 512
+        },
+        "notes": {
+          "type": "string",
+          "maxLength": 512
+        }
+      }
+    }
+  }
+}

package/bundled/skills/prizmkit-deploy/references/legacy-migration.md

@@ -0,0 +1,90 @@
+# Legacy Deployment State Migration
+
+Apply this procedure on first use whenever `.prizmkit/deploy/` exists, before creating or modifying `.prizmkit/deploy/deploy.json`. Legacy artifacts are evidence, not authorization and not current output formats.
+
+## Safety Invariants
+
+- Inventory and validation are read-only and project-scoped.
+- Never print, persist, hash, compare, or copy a Secret value.
+- Never delete, rename, truncate, normalize, or overwrite a legacy artifact during automatic migration.
+- Never continue a legacy writer after inventory, even when conversion is blocked.
+- Migrate only necessary, unambiguous, non-sensitive facts corroborated by current evidence.
+- Preserve uncertain, malformed, conflicting, Secret-bearing, or unconverted evidence in place.
+- A write to the sole record is an ordinary reversible write included in the complete confirmed plan. A source-artifact deletion or modification would require a separate exact dedicated confirmation and is not part of migration.
+- Existing project-native deployment configuration outranks legacy PrizmKit state.
+
+## Known Legacy Inventory
+
+Check only project-local paths that exist; do not create missing paths:
+
+| Legacy class | Known identity | Validation and conversion boundary |
+|---|---|---|
+| Configuration | `.prizmkit/deploy/deploy.config.json` and other clearly PrizmKit-owned config files in that directory | Parse without interpolation. Convert only target/profile references, environment labels, actual observed ports, native config paths, health definitions, release/rollback references, and Secret *names/source references*. Commands become evidence only and must be rediscovered before execution. |
+| Pending input | `.prizmkit/deploy/pending-input.json` | Validate shape and operation identity. Carry forward only a still-relevant non-sensitive pending action after rediscovery; otherwise preserve it and ask a fresh question. Never trust it as confirmation. |
+| Generated document | `.prizmkit/deploy/deploy.md` | Treat as human-readable, potentially stale evidence. Convert a fact only when corroborated by project-native or current target evidence. Never generate or update this document. |
+| Per-event history | `.prizmkit/deploy/deploy-history/*.json` | Parse each bounded file independently. Convert only concise redacted summaries from valid events, newest first, then retain at most the sole-record history limit. Preserve every source file. Never write another event file. |
+| Local Secret material | `.prizmkit/deploy/secrets.local.env`, `.prizmkit/deploy/secrets.local.json`, or another clearly Secret-bearing legacy path | Validate path ownership/ignore/permission metadata without displaying content. Do not import values. When safe key-name parsing is necessary and authorized, retain only names, external source reference, and presence; malformed or unsafe content stays untouched. Never create replacement local Secret storage. |
+| Target metadata copy/reference | `deploy-metadata.json` or a recorded target metadata path | Treat as stale until compared with current target-native read-only state. Convert only verified release/health/rollback facts. Do not recreate the fixed metadata format. |
+| Event/template/script artifact | Any per-release, per-phase, per-target, generated script, archive recipe, or template under the legacy directory | Preserve as evidence. Do not execute, regenerate, migrate as authority, or continue its naming pattern. |
+
+Do not recursively scan unrelated project content or follow symlinks outside the project. Record a symlink escape or unreadable artifact as a conflict and preserve it untouched.
+
+## Procedure
+
+### 1. Inventory
+
+1. List the existing `.prizmkit/deploy/` entries without following external symlinks.
+2. Classify each path by the table above or `unknown legacy evidence`.
+3. Record path, class, readability, and validation result without content excerpts that may contain Secrets.
+4. If `deploy.json` already exists, validate it first. Legacy evidence discovered later does not merge automatically into an established record.
+
+### 2. Validate Independently
+
+- Parse structured artifacts with strict duplicate-key and type checking where the current environment supports it.
+- Reject unknown legacy schema versions as conversion authority; preserve them.
+- Treat free-form documents, commands, timestamps, and recorded validation flags as stale claims.
+- Check project-native configuration and current read-only target observations before accepting target identity, ports, live release, health, or rollback.
+- Detect Secret-like field names and values before any preview. Omit values entirely; do not mask and carry them into the new record.
+- Do not resolve a conflict by choosing the newest timestamp alone.
+
+Invalid input does not block read-only discovery, but it blocks conversion of that input and any write that would silently discard its meaning.
+
+### 3. Build a Migration Preview
+
+Present one bounded preview containing:
+
+- source paths and validation statuses;
+- exact non-sensitive facts proposed for `project`, `profiles`, `secret_references`, `current`, bounded `history`, or `recovery`;
+- every conflict or stale/unverified claim;
+- every preserved path;
+- facts intentionally omitted and why;
+- the exact complete resulting `.prizmkit/deploy/deploy.json`.
+
+The preview must not contain legacy Secret values, full logs, raw command output, or unbounded event content.
+
+### 4. Confirm and Write Once
+
+When the user confirms the complete plan containing the migration:
+
+1. recheck that every inventoried source path and current evidence used by the preview is unchanged;
+2. validate the complete candidate against `${SKILL_DIR}/references/deploy-record-schema.json`;
+3. create `.prizmkit/deploy/` only if needed and included in the plan;
+4. write a temporary file in the same directory, flush/close it, validate it again, and atomically replace `deploy.json` without following a symlink;
+5. read back and validate the exact written object;
+6. leave every legacy source in place;
+7. stop with `FAILED` if record verification fails, preserving both the live state and legacy evidence.
+
+Do not claim that atomic replacement provides concurrent-writer safety. This contract assumes one operator.
+
+## Conflict and Failure Outcomes
+
+- **Unambiguous conversion:** write the fact and mark its source `MIGRATED_NON_SECRET`.
+- **Secret-bearing source:** keep values untouched, store at most a reference/presence fact, mark `PRESERVED_SECRET`.
+- **Malformed or unknown source:** preserve it, mark `INVALID` or `PRESERVED_UNCERTAIN`, and describe the blocker without sensitive content.
+- **Conflicting current facts:** use direct current evidence for execution, preserve the legacy conflict in `legacy_migration.conflicts`, and require confirmation of the resulting plan.
+- **Unknown write outcome:** inspect whether `deploy.json` exists and validates before any replay; never overwrite merely because the client timed out.
+- **No confirmation:** make no managed write and return `WAITING_USER` when a migration write is necessary for continuation.
+
+## After Migration
+
+Subsequent operations read and update only `deploy.json` for PrizmKit local state. Legacy paths remain read-only evidence until the user separately chooses exact cleanup. Never create or update legacy configuration, pending-input, document, metadata, Secret, template, script, archive, or per-event history artifacts.

package/bundled/skills/prizmkit-deploy/references/policy-and-execution.md

@@ -0,0 +1,170 @@
+# Deployment Policy and Execution Contract
+
+Use this contract for every deploy or mutating online operation, regardless of whether its capabilities are verified, dynamic, manual, or mixed. It also determines when an apparently read-only request must become a mutating plan.
+
+## Side-Effect Classification
+
+| Class | Examples by effect | Policy |
+|---|---|---|
+| `read_only` | Project-native file reads, non-mutating capability/version/auth identity probes, status, configured health reads, bounded logs, history, validation, bounded diagnostics | May run directly when proven project-scoped and read-only. Do not update the local record as a side effect. |
+| `reversible_write` | Create a release with verified cleanup, start/restart a project unit, update sole local record, apply project-scoped target configuration with verified restore | Show one complete immutable plan and obtain explicit confirmation before any step. |
+| `high_impact` | Project/source file change, privileged/global or compatibility-sensitive dependency change, shared infrastructure, traffic/data-affecting change, plan expansion, unknown-outcome replay, no reliable rollback | Obtain the complete-plan confirmation plus a dedicated confirmation at the exact boundary. |
+| `destructive` | Irreversible migration, data/resource deletion, overwrite without verified restore, destructive rollback | Obtain a dedicated confirmation identifying exact data/resources and recovery; refuse when impact cannot be bounded. |
+
+A command name, “dry-run” flag, target label, or recipe classification does not prove read-only behavior. Inspect documented effects and actual tool capability.
+
+## Immutable Plan
+
+The complete preview has one `plan_id` and a Secret-free digest over:
+
+- current project root and project/revision evidence;
+- target profile, endpoint/connection identity, environment, and actual observed ports;
+- requested operation and release/artifact identity;
+- all capability descriptors and ordered steps;
+- project/user dependencies and installed versions;
+- database/data analysis;
+- health boundary and verification layers;
+- rollback reference or explicit no-rollback state;
+- retry ceilings, human checkpoints, cleanup, and residual-resource policy;
+- local-record and optional project-file effects.
+
+Do not include Secret values in the digest input or preview. Bind only Secret names and external source references.
+
+Every ordered step contains every field below:
+
+| Field | Required content |
+|---|---|
+| `capability` | Semantic capability name. |
+| `availability` | `verified`, `dynamic`, `manual`, or `unsupported`. |
+| `evidence` | Bounded origin/observation/method/freshness facts supporting this exact step. |
+| `preconditions` | Rechecked immediately before execution. |
+| `inputs` | Non-sensitive values and Secret references, with source and identity. |
+| `effects` | Files, runtime units, releases, data, traffic, network, credential, cost, and residual resources affected. |
+| `risk` | `read_only`, `reversible_write`, `high_impact`, or `destructive`, plus reason. |
+| `confirmation` | `none`, `complete_plan`, and/or exact dedicated reason(s). |
+| `execution` | Complete executable/arguments, target-native action, or human action; target and working directory are explicit. |
+| `verification` | Required and optional observable postconditions. |
+| `failure_handling` | Stop, cleanup, inspection, rollback offer, and manual recovery behavior. |
+| `idempotency` | `proven`, `not_idempotent`, or `unknown`, with evidence. |
+| `retry` | Maximum attempts, retryable conditions, backoff/stop condition, and no-retry conditions. |
+| `unknown_outcome_inspection` | Proven read-only observation that distinguishes applied/not-applied/indeterminate before replay. |
+
+An unsupported required step makes the plan non-executable. A manual step is a human checkpoint and does not disappear from the order.
+
+Confirmation applies only to the exact digest. A changed command, argument, target identity, project revision, release input, effect, risk, dependency, migration, verification boundary, rollback state, or added step creates a new plan and invalidates prior confirmation.
+
+## Confirmation Matrix
+
+| Trigger | Confirmation required | Evidence shown before confirmation |
+|---|---|---|
+| Proven read-only and project-scoped | `none` | Target and bounded read effects |
+| Ordinary reversible writes | `complete_plan` | Entire ordered plan, effects, verification, rollback/cleanup, and digest |
+| Create or modify `prizmkit.deploy.json` or another project/source file | `PROJECT_FILE_CHANGE` | Exact complete file preview/diff, path, ownership, and rollback |
+| Privileged/global or compatibility-sensitive install/upgrade | `PRIVILEGED_OR_GLOBAL_DEPENDENCY` | Exact dependency/version/source, privilege, compatibility, target scope, effects, and uninstall/restore path |
+| Destructive or irreversible data migration | `DESTRUCTIVE_OR_IRREVERSIBLE_MIGRATION` | Exact migration, affected data, reversibility, locks/downtime, backup/restore evidence, and stop point |
+| Shared infrastructure or resource | `SHARED_INFRASTRUCTURE` | Exact shared resource, owners/consumers, traffic/cost/blast radius, and restore plan |
+| New scope or changed immutable plan | `PLAN_EXPANSION` | Complete replacement plan and change summary; old confirmation is void |
+| Possible prior write with unknown outcome | `UNKNOWN_WRITE_REPLAY` | Read-only inspection result, duplicate/replay effects, and exact replay action |
+| Deployment without verified rollback | `NO_RELIABLE_ROLLBACK` | Live-state risk, failure effects, residual resources, and manual recovery procedure |
+
+A dedicated confirmation supplements, not replaces, complete-plan confirmation. Capture the user's actual affirmative response and exact plan/reason scope in the active interaction. For interruption recovery, persist only a non-sensitive receipt containing confirmation kind, matching plan digest, and confirmation time; never persist unrelated conversation or Secret values. A request to deploy, initial feature request, silence, elapsed time, earlier approval, or approval of a different digest is not confirmation.
+
+If confirmation is unavailable in a non-interactive run, stop before the action with `WAITING_USER`, persist only confirmed minimal recovery context, and state the exact decision needed.
+
+## Dependencies and Installation
+
+1. Read project-native dependency/runtime declarations and lock/version files.
+2. Distinguish project-local, user-local, target-local, global, and privileged dependencies.
+3. Inspect actual installed versions and capabilities read-only.
+4. Prefer the project's declared package/dependency mechanism and pinned compatibility.
+5. Include every install, upgrade, source, version, scope, write, service restart, and restore path in the plan.
+6. Obtain `PRIVILEGED_OR_GLOBAL_DEPENDENCY` confirmation for privileged/global or compatibility-sensitive changes.
+7. Never silently install, upgrade, replace, remove, or select a guessed/wildcard version.
+8. Never transfer a controller-built dependency directory across systems unless project-native evidence explicitly establishes artifact portability and the confirmed package contract includes compatibility/integrity verification. Prefer reproducible target-compatible artifacts or target-native dependency resolution.
+
+A missing tool can make a capability `manual` or `unsupported`; it is not permission to install it.
+
+## Secret, Log, and Diagnostic Policy
+
+- Secret values remain in user/target-owned Secret systems. Plans contain names and source references only.
+- Never print or persist credentials in URLs, authorization headers, tokens, keys, cookies, connection strings, environment assignments, command arguments, or raw diagnostic output.
+- Before display, redact recognized credential syntax and user-identified sensitive patterns. Omit unnecessary lines rather than retaining masked copies.
+- Logs and diagnostics specify project-owned source, purpose, time range and/or line limit, filters, and redaction. Default to the smallest useful bounded window; do not stream indefinitely.
+- Do not run broad process, filesystem, network, account, or infrastructure inventory when a project-scoped observation answers the question.
+- If redaction cannot be made reliable, do not display or persist the content; provide a manual inspection checkpoint.
+
+## Database and Persistent-Data Gate
+
+Before any migration or data-affecting release step, report:
+
+1. exact migration identity and target data store;
+2. forward and reverse operations, or why reverse is impossible;
+3. tables/collections/files/queues and estimated data transformation/loss impact;
+4. lock level, downtime/online behavior, duration uncertainty, and traffic sequencing;
+5. compatibility window between old/new code and old/new schema;
+6. backup identity, completion, restore procedure, and restoration verification;
+7. expand/contract or other safer alternative when available;
+8. stop conditions, unknown-outcome inspection, and recovery owner.
+
+A migration tool reporting success does not prove data correctness. Verify schema/state and application health. Destructive or irreversible migration requires `DESTRUCTIVE_OR_IRREVERSIBLE_MIGRATION` confirmation. Never suppress a target/tool's own safety prompt.
+
+## Network and Shared Infrastructure
+
+Use actual observed connection and service ports. Distinguish controller-side connection endpoints from target-side application/listener endpoints. Do not infer ports from a platform label or fixed recipe.
+
+Any routing, certificate, firewall, load-balancer, domain, shared network, shared storage, shared database, or shared runtime change lists affected consumers and requires `SHARED_INFRASTRUCTURE` confirmation when it can affect another workload. General hardening or unrelated server administration is out of scope.
+
+## Operation Parity
+
+Every intent uses the same capability, planning, confirmation, and verification contracts:
+
+| Operation | Minimum behavior |
+|---|---|
+| `deploy` | Discover/validate; compile all build/package/transfer/configure/migrate/release/start/health dependencies that evidence requires. |
+| `status` | Observe current release/runtime state read-only; report inaccessible layers. |
+| `health` | Execute configured health boundary read-only and preserve required/optional distinction. |
+| `logs` | Read a bounded redacted project-owned window. |
+| `stop` | Observe the current project-owned unit, confirm the stop effects and rollback/start recovery, stop only that unit, and verify the intended offline/live state. |
+| `restart` | Observe current unit, confirm reversible write, restart only that unit, verify runtime/health/log layers. |
+| `rollback` | Verify rollback reference and current live state, confirm effects, restore, then run full applicable verification. |
+| `history` | Read concise bounded local and target-native release evidence without writing event files. |
+| `validate` | Check evidence, configuration, capability prerequisites, policy, and rollback without deployment writes. |
+| `diagnose` | Gather bounded read-only evidence; compile a new plan before any repair. |
+| `takeover` | Discover ownership/conflicts/backups/coexistence; dedicated confirmation applies to shared or non-owned changes. |
+| `resume` | Rediscover and compare evidence/digest before continuing; never assume the prior process completed nothing. |
+| `cancel` | Stop future actions and perform only already-confirmed safe cleanup; report residual resources. |
+
+## Execution Algorithm
+
+1. Revalidate project, target, authentication identity, current live state, and the step's evidence/preconditions.
+2. Verify that complete-plan and applicable dedicated confirmations match the current digest.
+3. Report `step N/total`, capability, action class, target boundary, and evidence being sought. Do not promise a universal duration.
+4. Execute exactly the planned action. Do not improvise flags, repairs, cleanup, scope, or dependencies.
+5. Capture only bounded redacted evidence and determine the immediate command/target result.
+6. Run the step verification before advancing.
+7. Atomically update the sole local record only at confirmed plan points; validate before and after write.
+8. Stop at a human checkpoint, failure, unknown outcome, invalidated plan, cancellation, or terminal verification.
+
+## Retry and Unknown Outcomes
+
+- Automatic retry is permitted only for a proven read-only action or a proven idempotent action under its explicit maximum-attempt and stop-condition policy.
+- Retry count is bounded in the immutable plan; never convert a bounded retry into an open loop.
+- Authentication denial, invalid input, destructive failure, plan mismatch, failed required verification, and unknown write outcome are not automatic-retry conditions.
+- After timeout, disconnect, or lost response during a possible write, run the planned read-only inspection. Classify the effect as applied, not applied, or indeterminate.
+- `applied`: verify postconditions; do not replay.
+- `not applied`: retry only if idempotency/retry policy allows and confirmation remains valid.
+- `indeterminate`: stop with `BLOCKED` or `WAITING_USER`; any replay requires `UNKNOWN_WRITE_REPLAY` confirmation.
+
+## Deterministic Policy Cases
+
+| Case | Required outcome |
+|---|---|
+| Read-only project status with proven non-mutating probe | Execute directly; no local-record write |
+| Ordinary reversible restart | Complete-plan confirmation before write |
+| User requested deploy but has not approved compiled plan | `WAITING_USER` |
+| Plan gains an unpreviewed configuration write | New plan plus `PLAN_EXPANSION`; no execution |
+| Required privileged dependency is missing | Dedicated confirmation or `WAITING_USER`; no silent install |
+| Migration is irreversible and impact cannot be bounded | `BLOCKED` |
+| Prior write timed out and inspection is indeterminate | No replay; `BLOCKED` or `WAITING_USER` |
+| Rollback is absent but exact risk is accepted | Deployment may proceed; retain explicit manual recovery |
+| Required health check fails after release command succeeds | `FAILED`; command success is not operation success |

package/bundled/skills/prizmkit-deploy/references/real-resource-test-policy.md

@@ -0,0 +1,73 @@
+# Real-Resource Test Policy
+
+Local fixtures and side-effect-free contract tests may run without a deployment confirmation. A test crosses the real-resource boundary if it connects to or authenticates against a server, remote target/control plane, real database, credential store, external URL that creates meaningful traffic, or any resource that may create state, traffic, side effects, quota use, or cost.
+
+A “smoke test,” read-only label, sandbox label, free tier, dry-run flag, or non-production name does not bypass this boundary.
+
+## Deterministic Local Tests
+
+These may run normally when they use only local temporary fixtures and no external credentials or network:
+
+- capability availability and evidence-precedence cases;
+- immutable plan and confirmation-policy cases;
+- operation/command/config schema parity;
+- JSON schema closed-shape and terminal-status checks;
+- Secret-like fixture redaction and persistence rejection;
+- bounded history/log/recovery/minimal-state checks;
+- failure injection for command failure, health failure, unknown write, manual checkpoint, rollback absence, and local-record failure;
+- canonical source, generated bundle, and isolated temporary Host installation parity.
+
+Use synthetic Secret values that cannot be mistaken for live credentials. Tests must not read the operator's environment, credential files, login state, browser profile, keychain, or target configuration.
+
+## Separate Authorization Preview
+
+Before any real-resource test, present one dedicated preview containing every field:
+
+| Field | Required content |
+|---|---|
+| `target` | Exact account/project/resource/profile and environment; no Secret values. |
+| `connection` | Controller boundary, endpoint reference, and actual connection/service ports. |
+| `credentials` | Secret names/source references and identity to be used, never values. |
+| `actions` | Exact read/write/authentication/network/database/traffic operations and commands/actions. |
+| `effects` | Possible state, traffic, data, quota, billing, notification, audit-log, and rate-limit effects. |
+| `duration` | Bounded test window or command timeout; state uncertainty explicitly, never promise a universal completion time. |
+| `cleanup` | Exact cleanup actions, ownership, verification, and what remains if cleanup fails. |
+| `rollback` | Verified rollback or explicit absence and manual recovery. |
+| `logs` | Bounded sources, line/time limits, filters, redaction, and persistence policy. |
+| `stop_conditions` | Authentication, cost, traffic, data, health, timeout, and unknown-outcome conditions that stop the test. |
+
+Ask for separate explicit authorization of this exact preview. Approval of a feature, deployment plan, local test suite, or earlier smoke test is not real-resource test authorization. Any changed target, identity, action, effect, duration, cleanup, cost, or scope invalidates authorization.
+
+In a non-interactive session without exact authorization, do not connect. Return `WAITING_USER` with the non-sensitive preview or `BLOCKED` when the target/effects cannot be bounded.
+
+## Execution
+
+When authorized:
+
+1. revalidate target and authentication identity read-only;
+2. apply the ordinary deployment policy and all dedicated confirmations in addition to this test authorization;
+3. execute only the previewed bounded actions;
+4. report progress without a universal duration promise;
+5. stop on any previewed condition, plan mismatch, unknown write outcome, credential boundary change, or unexpected cost/traffic/state;
+6. run layered verification and bounded redaction;
+7. perform only authorized cleanup;
+8. verify cleanup independently and report residual resources.
+
+Unknown writes are inspected before replay. A test command exit is not proof that setup, traffic, state, or cleanup succeeded.
+
+## Result and Cleanup Failure
+
+Report the test result separately from cleanup:
+
+- test terminal status and verification layers;
+- target and identity actually used;
+- effects and traffic/state/cost observed;
+- created or modified resources;
+- cleanup actions and verification;
+- every residual resource and manual cleanup step.
+
+If the test passes but cleanup fails or cannot be verified, do not report an unqualified success. Return `FAILED` for a required cleanup failure or `BLOCKED` for an inaccessible/indeterminate cleanup boundary, and state that resources may remain.
+
+## This Framework Feature's Test Boundary
+
+The deployment Skill's framework contract tests are deterministic local tests only. They must not connect to a server, remote target/control plane, real database, credential boundary, or traffic/state/cost-bearing resource. No real-resource smoke test is implied or pre-authorized by installing or invoking this Skill.