prizmkit 1.1.153 → 1.1.155

package/bundled/skills/prizmkit-deploy/SKILL.md

@@ -75,7 +75,7 @@ Priority:
 2. Existing config: `.prizmkit/deploy/deploy.config.json`
 3. Project files: `vercel.json`, `netlify.toml`, `fly.toml`, `Dockerfile`, `docker-compose.yml`, GitHub deploy workflow, `app.yaml`, `serverless.yml`
 4. Interactive question: ask where the project should be deployed
-5. Headless with missing target: exit `NEEDS_INPUT` and write pending questions to `.prizmkit/deploy/pending-input.json`
+5. Headless with missing target: exit `NEEDS_INPUT` and atomically write `.prizmkit/deploy/pending-input.json` conforming to `${SKILL_DIR}/references/pending-input-schema.json`
 
 ## Adapter Routing
 
@@ -99,7 +99,8 @@ Headless mode:
 - Never wait for user input.
 - May target only dev or test environments.
 - Reject production with `ENVIRONMENT_DENIED`.
-- If required info is missing, exit `NEEDS_INPUT` and write `.prizmkit/deploy/pending-input.json`.
+- If required info is missing, exit `NEEDS_INPUT` and atomically write `.prizmkit/deploy/pending-input.json` from `${SKILL_DIR}/references/pending-input-schema.json`. Include only unanswered non-secret configuration questions, replace stale pending content on each attempt, and delete the file after those inputs are resolved and persisted.
+- Never request passwords, tokens, private keys, connection strings, or other secret values through `pending-input.json`.
 - Perform only actions already authorized by `deploy.config.json`.
 
 ## Command Routing
@@ -126,20 +127,33 @@ No-arg behavior:
 
 ## Artifact Structure
 
-All deployment artifacts live under `.prizmkit/deploy/`:
+Managed deployment artifacts live under `.prizmkit/deploy/`:
 
 ```text
 .prizmkit/deploy/
   deploy.md
   deploy.config.json
-  pending-input.json
+  pending-input.json        # present only while non-secret input is unresolved
   deploy-history/
-  deploy-scripts/
-  secrets.enc.json
-  secrets.local.json
+  secrets.local.env         # optional, ignored, permission-restricted dotenv data
 ```
 
-Read `references/deploy-config-schema.md` when writing or validating config. Read `references/deploy-history-schema.md` when writing history records.
+Read `${SKILL_DIR}/references/deploy-config-schema.md` when writing or validating config, `${SKILL_DIR}/references/deploy-history-schema.md` when writing history records, `${SKILL_DIR}/references/pending-input-schema.json` when writing unresolved questions, and `${SKILL_DIR}/assets/deploy-document-template.md` whenever creating or updating `deploy.md`.
+
+`secrets.local.env` contains dotenv `KEY=value` lines, never JSON. Verify an exact ignore rule and current-user-only permissions before writing it. Encrypted-secret files and generated deployment scripts are not supported artifacts; do not advertise or create them.
+
+Other files are generated only through these explicit target-native contracts:
+
+| Output | Naming/content contract |
+|---|---|
+| `.github/workflows/deploy.yml` | `references/ci-cd-workflows.md` |
+| `vercel.json`, `netlify.toml`, `fly.toml` | `references/cloud-platform-deploy.md`; generate only the selected platform file |
+| `deploy-<releaseId>.tar.gz` | `references/direct-upload.md` or CI workflow template |
+| `/etc/nginx/sites-available/<project>` | `references/nginx-blue-green.md` managed template and marker |
+| `<server-project>/shared/.env.production` | strict permission-restricted dotenv contract in `references/ssh-adapter-flow.md` |
+| `<server-project>/shared/deploy-metadata.json` | `references/deploy-metadata-schema.json` |
+
+Do not generate another framework-owned deployment file until its deterministic identity, writer, update/overwrite policy, secret boundary, and complete content contract are added here.
 
 Reference index:
 - `references/ssh-adapter-flow.md` — load when routing to SSH Linux full automation.
@@ -149,6 +163,8 @@ Reference index:
 - `references/dns-setup.md`, `references/ssl-setup.md` — load for domain and HTTPS setup.
 - `references/ssh-execution-flow.md`, `references/nginx-blue-green.md`, `references/ssh-takeover.md` — load for deploy execution, traffic switching, rollback, or takeover.
 - `references/cloud-platform-deploy.md`, `references/docker-deploy.md` — load for non-SSH guided routes.
+- `references/pending-input-schema.json`, `assets/deploy-document-template.md` — load for managed pending-input and deployment-document writes.
+- `references/deploy-metadata-schema.json` — load for atomic server active-slot metadata writes after verified SSH deploy/rollback operations.
 - `references/live-validation-notes.md` — load when troubleshooting bootstrap or deploy failures.
 
 Never record raw secret values in config, docs, or history. Secret presence metadata is allowed; raw values and unsalted hashes are not.
@@ -179,7 +195,7 @@ Key invariants:
 Cloud platforms:
 - Read `references/cloud-platform-deploy.md`.
 - Detect required CLI/account steps.
-- Generate or update deploy documentation and config.
+- Generate or update config and render `deploy.md` from `${SKILL_DIR}/assets/deploy-document-template.md` without duplicate headings.
 - Guide the user through interactive login or dashboard steps when needed.
 
 Docker:
@@ -193,8 +209,8 @@ Docker:
 When no adapter covers the detected target/project type:
 
 1. Detect what you can: language, framework, build/start commands, env vars, port usage, databases.
-2. Generate `.prizmkit/deploy/deploy.md` with prerequisites, env vars, build/start instructions, health checks, and manual steps.
-3. Record adapter gap in deploy history: missing adapter, detected project type, target, fallback output.
+2. Render `.prizmkit/deploy/deploy.md` from `${SKILL_DIR}/assets/deploy-document-template.md`, filling prerequisites, environment-variable names, build/start instructions, health checks, rollback limits, and manual actions.
+3. Record adapter gap in deploy history using the event identity and content contract in `${SKILL_DIR}/references/deploy-history-schema.md`: missing adapter, detected project type, target, and fallback output.
 4. Offer to generate basic CI/CD config when applicable.
 
 ## Validation

package/bundled/skills/prizmkit-deploy/assets/deploy-document-template.md

@@ -0,0 +1,89 @@
+# Deployment Document Template
+
+Render `.prizmkit/deploy/deploy.md` with the exact top-level headings below. Replace placeholders with established values, use `not configured` or `not applicable` when truthful, and never write raw secret values. Update sections in place; do not append duplicate headings or turn this document into deployment history. Immutable operation events belong in `deploy-history/`.
+
+```markdown
+# Deployment
+
+## Target
+
+- Project: <project name>
+- Project type: <detected project type>
+- Environment: <dev | test | production>
+- Target: <SSH host alias | cloud platform | Docker | unsupported target>
+- Adapter: <ssh | cloud-guided | docker-guided | documented-fallback>
+- Strategy: <push | pull | direct-upload | platform-native | container-native | manual>
+- Public URL: <URL | not configured>
+
+## Prerequisites
+
+- <required runtime/tool/account/connectivity prerequisite>
+
+## Required Environment Variables
+
+Record names, purpose, source, and presence only. Never record values.
+
+| Name | Required | Purpose | Secret Source | Present |
+|---|---|---|---|---|
+| `<VARIABLE_NAME>` | yes | <purpose> | <platform secret store or ignored local env file> | yes/no |
+
+## Build and Release
+
+- Install command: `<command | not required>`
+- Build command: `<command | not required>`
+- Start command: `<command>`
+- Release layout: <path/layout or platform-native>
+- Artifact source: <repository checkout | uploaded archive | container image | platform build>
+
+## Runtime
+
+- Process manager: <manager | platform-native>
+- Runtime user: <user | platform-managed>
+- Internal port: <port | platform-managed>
+- Public routing: <Nginx/proxy/platform route>
+- Persistent storage: <mounts/volumes | none>
+
+## Health Checks
+
+| Name | URL or Command | Expected | Last Verified Result |
+|---|---|---|---|
+| <check> | <path/command> | <status/output> | <pass/fail/not run> |
+
+## DNS and TLS
+
+- Domain: <domain | not configured>
+- DNS status: <configured/pending/not applicable>
+- TLS issuer: <issuer | platform-managed | not configured>
+- Renewal: <automatic/manual/not applicable>
+
+## Rollback
+
+- Strategy: <previous release/platform rollback/image rollback/manual>
+- Command or procedure: <safe rollback command/procedure>
+- Readiness: <verified/not verified/not applicable>
+
+## Operations
+
+- Status: `<command or platform action>`
+- Logs: `<command or platform action>`
+- Restart: `<command or platform action>`
+- Health: `<command or platform action>`
+- Rollback: `<command or platform action>`
+
+## Current Validation
+
+- Configuration: <pass/fail/not run>
+- Connectivity: <pass/fail/not run>
+- Build: <pass/fail/not run>
+- Staged health: <pass/fail/not run>
+- Live health: <pass/fail/not run>
+- Latest history record: `.prizmkit/deploy/deploy-history/<event-id>.json` or `none`
+
+## Manual Actions
+
+- <remaining user-owned action, or `None`>
+
+## Notes
+
+- <stable deployment constraint, adapter gap, or operational warning>
+```

package/bundled/skills/prizmkit-deploy/references/ci-cd-workflows.md

@@ -43,6 +43,9 @@ jobs:
         with:
           node-version: 20
 
+      - name: Allocate Release Identity
+        run: echo "ARCHIVE_ID=$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short=12 HEAD)" >> "$GITHUB_ENV"
+
       - name: Install & Build
         run: |
           npm ci
@@ -50,26 +53,35 @@ jobs:
 
       - name: Package & Transfer
         run: |
-          RELEASE_ID=$(date +%Y%m%d)-$(git rev-parse --short HEAD)
-          tar czf deploy-$RELEASE_ID.tar.gz \
+          tar czf deploy-$ARCHIVE_ID.tar.gz \
             <build-output-dir>/ node_modules/ package.json package-lock.json
-          scp -P ${{ secrets.SSH_PORT }} deploy-$RELEASE_ID.tar.gz \
+          scp -P ${{ secrets.SSH_PORT }} deploy-$ARCHIVE_ID.tar.gz \
             ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:/var/www/<project>/releases/
 
       - name: Deploy on Server
         uses: appleboy/ssh-action@v1
+        env:
+          ARCHIVE_ID: ${{ env.ARCHIVE_ID }}
         with:
           host: ${{ secrets.SSH_HOST }}
           username: ${{ secrets.SSH_USER }}
           key: ${{ secrets.SSH_KEY }}
           port: ${{ secrets.SSH_PORT }}
+          envs: ARCHIVE_ID
           script: |
+            set -eu
             cd /var/www/<project>
-            RELEASE_ID=$(date +%Y%m%d)-$(git rev-parse --short HEAD)
-            mkdir -p releases/$RELEASE_ID
-            tar xzf releases/deploy-$RELEASE_ID.tar.gz -C releases/$RELEASE_ID
-            rm releases/deploy-$RELEASE_ID.tar.gz
-            # PM2 start, health check, Nginx switch (same as manual flow)
+            RELEASE_ID="$ARCHIVE_ID"
+            SUFFIX=1
+            while [ -e "releases/$RELEASE_ID" ]; do
+              [ "$SUFFIX" -le 99 ] || { echo "release identity suffixes exhausted" >&2; exit 1; }
+              RELEASE_ID="$ARCHIVE_ID-$(printf '%02d' "$SUFFIX")"
+              SUFFIX=$((SUFFIX + 1))
+            done
+            mkdir "releases/$RELEASE_ID"
+            tar xzf "releases/deploy-$ARCHIVE_ID.tar.gz" -C "releases/$RELEASE_ID"
+            rm "releases/deploy-$ARCHIVE_ID.tar.gz"
+            # PM2 start, health check, Nginx switch, history, and metadata use RELEASE_ID
 ```
 
 **Key difference from Pull:** the runner checks out code, installs, builds, and only transmits the result. The server doesn't need Git or build tools — just Node.js runtime and PM2.
@@ -91,23 +103,41 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/checkout@v4
+
+      - name: Allocate Release Identity
+        run: |
+          echo "RELEASE_BASE=$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short=12 HEAD)" >> "$GITHUB_ENV"
+          echo "DEPLOY_SHA=$(git rev-parse HEAD)" >> "$GITHUB_ENV"
+
       - name: Trigger Server Deploy
         uses: appleboy/ssh-action@v1
+        env:
+          RELEASE_BASE: ${{ env.RELEASE_BASE }}
+          DEPLOY_SHA: ${{ env.DEPLOY_SHA }}
         with:
           host: ${{ secrets.SSH_HOST }}
           username: ${{ secrets.SSH_USER }}
           key: ${{ secrets.SSH_KEY }}
           port: ${{ secrets.SSH_PORT }}
+          envs: RELEASE_BASE,DEPLOY_SHA
           script: |
+            set -eu
             cd /var/www/<project>
-            RELEASE_ID=$(date +%Y%m%d)-$(git rev-parse --short HEAD)
-            mkdir -p releases/$RELEASE_ID
-            git clone <repoUrl> --branch <branch> releases/$RELEASE_ID
-            cd releases/$RELEASE_ID
+            RELEASE_ID="$RELEASE_BASE"
+            SUFFIX=1
+            while [ -e "releases/$RELEASE_ID" ]; do
+              [ "$SUFFIX" -le 99 ] || { echo "release identity suffixes exhausted" >&2; exit 1; }
+              RELEASE_ID="$RELEASE_BASE-$(printf '%02d' "$SUFFIX")"
+              SUFFIX=$((SUFFIX + 1))
+            done
+            git clone --no-checkout --branch <branch> <repoUrl> "releases/$RELEASE_ID"
+            git -C "releases/$RELEASE_ID" checkout --detach "$DEPLOY_SHA"
+            cd "releases/$RELEASE_ID"
             npm ci
-            cp ../shared/.env.production .
+            cp ../../shared/.env.production .
             npm run build
-            # PM2 start, health check, Nginx switch
+            # PM2 start, health check, Nginx switch, history, and metadata use RELEASE_ID
 ```
 
 **Key difference from Push:** the workflow is simpler (one step: SSH + run script), but the server needs Git, full build toolchain, and must be able to reach the repo.

package/bundled/skills/prizmkit-deploy/references/cloud-platform-deploy.md

@@ -40,7 +40,23 @@ Platform rollback is instant — no release-based rollback needed.
 
 ### Vercel
 
-Vercel auto-detects Next.js projects — no config file required for basic deployments. Generate `vercel.json` only for custom rewrites, redirects, or headers.
+Vercel auto-detects Next.js projects — no config file is generated for basic deployments. When confirmed custom routing or static build settings require `vercel.json`, start from this minimal platform-native shape and include only established keys:
+
+```json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "buildCommand": "npm run build",
+  "outputDirectory": "dist",
+  "rewrites": [
+    {
+      "source": "/(.*)",
+      "destination": "/index.html"
+    }
+  ]
+}
+```
+
+Omit `buildCommand`/`outputDirectory` when framework detection owns them, and omit `rewrites` unless the application actually needs SPA fallback or a confirmed route. Validate generated configuration with the installed Vercel CLI before deployment.
 
 Key behaviors:
 - Next.js: framework auto-detected, build command and output directory inferred automatically
@@ -77,7 +93,7 @@ app = "<app-name>"
 primary_region = "lhr"
 
 [build]
-  builder = "dockerfile"
+  dockerfile = "Dockerfile"
 
 [http_service]
   internal_port = 3000
@@ -85,7 +101,7 @@ primary_region = "lhr"
 ```
 
 Key behaviors:
-- Builder: `dockerfile` (default, uses Dockerfile) or `static` (static site hosting)
+- Build source: `dockerfile = "Dockerfile"` for project-owned images, or a confirmed platform-supported image/build configuration; static sites still need a valid serving image rather than an invented `static` builder value
 - Secrets: `fly secrets set <KEY>=<VALUE>` for runtime environment variables
 - Scale: `fly scale count <N>` to adjust VM instances
 - Volumes: for persistent data, configure `[mounts]` in fly.toml

package/bundled/skills/prizmkit-deploy/references/database-setup.md

@@ -12,12 +12,13 @@ During Discovery Step 1 (Project Detection), database drivers were already scann
 
 ## Secrets file safety
 
-Before writing `.prizmkit/deploy/secrets.local.json`:
+Before writing `.prizmkit/deploy/secrets.local.env`:
 
-1. Verify `.gitignore` or an equivalent ignore rule covers `.prizmkit/deploy/secrets.local.json` and any `.prizmkit/deploy/*.local.json` pattern used by the project.
-2. If the ignore rule is missing, pause and add or request the ignore rule before writing secrets.
-3. Set the secrets file permissions to current-user read/write only, for example `chmod 600 .prizmkit/deploy/secrets.local.json` on POSIX systems.
-4. Record only presence metadata in deploy config, docs, reports, and history. Never copy raw passwords, connection strings, passphrases, decryption keys, unsalted hashes, or full env var values into committed files.
+1. Verify `.gitignore` or an equivalent ignore rule covers the exact `.prizmkit/deploy/secrets.local.env` path or a compatible `.prizmkit/deploy/*.local.env` pattern.
+2. If the ignore rule is missing, pause and add or request it before writing secrets.
+3. Create/update the file with restrictive creation permissions (for example `umask 077` on POSIX), atomically replace it without widening permissions, set mode `600`, and verify it is ignored by Git.
+4. Use dotenv syntax: one `KEY=value` assignment per line, UTF-8, no JSON braces or commas. Preserve unrelated existing assignments and reject malformed or duplicate keys.
+5. Record only presence metadata in deploy config, docs, reports, and history. Never copy raw passwords, connection strings, passphrases, decryption keys, unsalted hashes, or full env var values into committed files.
 
 ```
 apt-get install -y postgresql postgresql-contrib
@@ -26,10 +27,19 @@ sudo -u postgres psql -c "CREATE USER <project> WITH PASSWORD '<random-password>
 sudo -u postgres psql -c "GRANT ALL ON DATABASE <project> TO <project>;"
 ```
 
-- Generate a secure random password (32 chars, alphanumeric + symbols).
-- Write the connection string to `.prizmkit/deploy/secrets.local.json`: `DATABASE_URL=postgresql://<project>:<password>@localhost:5432/<project>`.
-- Set `.prizmkit/deploy/secrets.local.json` permissions to current-user read/write only after writing.
-- In deploy.md, write: "PostgreSQL installed, connection info recorded in `.prizmkit/deploy/secrets.local.json` (gitignored; raw value not committed)".
+- Generate a cryptographically secure 32-character URL-safe password using letters, digits, `_`, and `-`, with no whitespace, quotes, `#`, or `=`.
+- Write or replace the single dotenv assignment `DATABASE_URL=postgresql://<project>:<password>@localhost:5432/<project>` in `.prizmkit/deploy/secrets.local.env`.
+- Re-verify ignore status and current-user-only permissions after atomic replacement.
+- In `deploy.md`, record only: "PostgreSQL connection information is stored in ignored local secret storage; raw values are not committed."
+
+## Legacy Local-Secret Migration
+
+If `.prizmkit/deploy/secrets.local.json` already exists from an earlier installation, treat the filename as legacy input only, never as a current output:
+
+1. Verify it is ignored by Git and restricted to the current user before reading it.
+2. Detect either a JSON object containing string values or strict dotenv `KEY=value` lines; reject mixed, malformed, duplicate, or non-string content without printing values.
+3. Convert the validated assignments to `.prizmkit/deploy/secrets.local.env` through the restrictive atomic-write rules above.
+4. Compare key names and presence only. Remove the legacy file only after successful conversion and explicit user confirmation; otherwise leave it untouched and report migration pending.
 
 ## MySQL setup (future)
 
@@ -44,12 +54,12 @@ redis-cli CONFIG REWRITE
 ```
 
 - Bind to localhost only (modify `/etc/redis/redis.conf` if needed).
-- Write `REDIS_URL=redis://:<password>@localhost:6379` to `.prizmkit/deploy/secrets.local.json`.
-- Set `.prizmkit/deploy/secrets.local.json` permissions to current-user read/write only after writing.
+- Write or replace the single dotenv assignment `REDIS_URL=redis://:<password>@localhost:6379` in `.prizmkit/deploy/secrets.local.env` using the same URL-safe password and atomic permission rules.
+- Re-verify ignore status and current-user-only permissions after replacement.
 
 ## Security notes
 
 - Never write database passwords to deploy.md, because deploy.md may be committed to git and passwords would leak.
-- Passwords stored in `.prizmkit/deploy/secrets.local.json` only after verifying the file is ignored by git and locked down to current-user read/write permissions.
+- Passwords are stored only in `.prizmkit/deploy/secrets.local.env` after verifying the file is ignored by Git and locked down to current-user read/write permissions.
 - Default: database binds to localhost, no external access, because most indie projects only need local connections.
 - Record a `"database-setup"` event in deploy history (presence metadata only, no passwords).

package/bundled/skills/prizmkit-deploy/references/deploy-config-schema.md

@@ -26,12 +26,14 @@ This file is the machine-readable deployment configuration. Always read it befor
 {
   "releaseRetention": 5,
   "credentialMode": "ai-assisted|user-managed",
-  "secretStorage": "ask-every-time|encrypted-local|plaintext-local|user-managed-on-server-only",
+  "secretStorage": "ask-every-time|ignored-local-env|user-managed-on-server-only",
   "rollbackOnFailure": true,
   "headlessDefaultEnvironment": "test"
 }
 ```
 
+`ignored-local-env` means `.prizmkit/deploy/secrets.local.env` after exact ignore and permission verification. Legacy `plaintext-local` may be migrated only through the local-secret migration contract. Legacy `encrypted-local` is unsupported because this Skill has no encryption/key-management implementation; block deployment and require the user to select a supported mode without exposing secret values.
+
 ## environments
 
 Keyed by environment name. Each entry:

package/bundled/skills/prizmkit-deploy/references/deploy-history-schema.md

@@ -1,17 +1,18 @@
 # Deploy History Record Schema
 
-Each event in `.prizmkit/deploy/deploy-history/<id>.json` follows this schema:
+Each immutable event is written atomically to `.prizmkit/deploy/deploy-history/<eventId>.json`. The filename stem must equal the JSON `eventId` exactly.
 
 ```json
 {
-  "eventId": "<releaseId or event id>",
-  "eventType": "deploy|rollback|status|validation|failed-deploy|user-aborted|takeover|adapter-gap",
-  "timestamp": "<ISO 8601>",
+  "eventId": "deploy-20260430T142233Z-22783a3",
+  "eventType": "deploy|rollback|status|validation|failed-deploy|user-aborted|takeover|adapter-gap|database-setup",
+  "timestamp": "<ISO 8601 UTC>",
+  "releaseId": "20260430T142233Z-22783a3 or null",
   "serverId": "<server id from deploy.config.json>",
   "appIds": ["<app ids involved>"],
   "branch": "<git branch>",
   "commitSha": "<full or short commit SHA>",
-  "releasePath": "<full server path, e.g. /var/www/prizm-ideas/releases/20260430-22783a3>",
+  "releasePath": "<full server path, e.g. /var/www/prizm-ideas/releases/20260430T142233Z-22783a3>",
   "previousReleasePath": "<previous release path or null for first deploy>",
   "targetPort": 3101,
   "targetColor": "blue|green",
@@ -45,9 +46,24 @@ Each event in `.prizmkit/deploy/deploy-history/<id>.json` follows this schema:
 }
 ```
 
+## Event and File Identity
+
+Generate every `eventId` as:
+
+```text
+<event-type>-<UTC-compact-timestamp>-<short-sha-or-none>[-NN]
+```
+
+Rules:
+
+- `UTC-compact-timestamp` is the event time formatted `YYYYMMDDTHHMMSSZ`.
+- `short-sha` is the lowercase 7-12 hexadecimal commit prefix when a commit exists; otherwise use literal `none`.
+- If the candidate filename already exists, append the lowest available two-digit suffix from `-01` through `-99`; never overwrite a history record. If all suffixes are occupied, stop with a recording error.
+- Use the exact event ID as the filename stem. Example: `rollback-20260430T151000Z-22783a3.json`.
+- `releaseId` is a separate deployment/release-directory identity. Set it to the affected release for deploy, failed-deploy, and rollback events; otherwise use `null` when no release applies.
+
 ## Field Notes
 
-- `eventId`: Use `<releaseId>` for deploy events, `<releaseId>-rollback` for rollbacks.
 - `eventType`: Use `failed-deploy` when deploy fails before traffic switch, `deploy` when it succeeds. Use `adapter-gap` when no adapter exists for the detected project type or target — include `detectedProjectType`, `missingAdapter`, and `fallbackOutput` in the record.
 - `phases`: Only include phases that were attempted. Skip phases that were never reached.
 - `healthCheckResults`: Include all configured health checks. `pass` = actual status matches one of the expected status codes.

package/bundled/skills/prizmkit-deploy/references/deploy-metadata-schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PrizmKit Server Deployment Metadata",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "activeColor",
+    "activePort",
+    "lastReleaseId",
+    "lastOperationEventId",
+    "updatedAt"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "activeColor": {
+      "enum": ["blue", "green"]
+    },
+    "activePort": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 65535
+    },
+    "lastReleaseId": {
+      "type": "string",
+      "pattern": "^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{7,12}(?:-[0-9]{2})?$"
+    },
+    "lastOperationEventId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z-]*-[0-9]{8}T[0-9]{6}Z-(?:[0-9a-f]{7,12}|none)(?:-[0-9]{2})?$"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "examples": [
+    {
+      "schema_version": 1,
+      "activeColor": "blue",
+      "activePort": 3101,
+      "lastReleaseId": "20260430T142233Z-22783a3",
+      "lastOperationEventId": "deploy-20260430T142233Z-22783a3",
+      "updatedAt": "2026-04-30T14:22:33Z"
+    }
+  ]
+}

package/bundled/skills/prizmkit-deploy/references/live-validation-notes.md

@@ -12,7 +12,7 @@ These findings from the first PrizmKit deployment (PrizmIdeas) guide edge-case h
 
 5. **`pm2 startup` needs explicit PATH.** Always use `env PATH=$PATH:/usr/bin pm2 startup ...`, because the pm2 binary may not be on root's default PATH.
 
-6. **Persist deploy metadata on server.** Write `activeColor`, `activePort`, `lastReleaseId`, `lastDeployTimestamp` to `shared/deploy-metadata.json`, because subsequent deploys and rollbacks depend on knowing the current active slot.
+6. **Persist deploy metadata on server.** After public health and history recording succeed, atomically write `shared/deploy-metadata.json` from `${SKILL_DIR}/references/deploy-metadata-schema.json`, including active color/port, release identity, operation event identity, and UTC update time. Subsequent deploys and rollbacks depend on this active-slot record.
 
 7. **Detect first deployment.** If no `current` symlink and no PM2 process for the app, skip rollback safety checks and use blue (3101) as initial color.