prizmkit 1.1.40 → 1.1.42

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

@@ -0,0 +1,93 @@
+# Cloud Platform Deployment Path
+
+Guided deployment for Vercel, Netlify, Fly.io, and similar cloud platforms. Full automation isn't available — these platforms require browser-based authentication — but the skill provides structured CLI assistance.
+
+## Detect and Validate
+
+1. Check if the platform CLI is installed: `vercel --version`, `netlify --version`, `fly version`.
+2. If missing, guide the user to install: `npm install -g vercel` or link to docs.
+3. Check authentication: `vercel whoami`, `netlify status`. If not logged in, guide the user through `vercel login`.
+4. Read the platform config file (`vercel.json`, `netlify.toml`, `fly.toml`) to understand existing settings.
+
+## Generate Configuration
+
+1. If no platform config file exists, generate one based on project detection:
+   - **Next.js on Vercel**: minimal config — Vercel auto-detects Next.js. Generate `vercel.json` only if custom rewrites/redirects are needed.
+   - **Static site on Netlify**: generate `netlify.toml` with build command and publish directory.
+   - **Any on Fly.io**: generate `fly.toml` with app name, builder, and HTTP service config.
+2. Set environment variables via the platform CLI: `vercel env add`, `netlify env:set`.
+3. Document all env vars needed (from Discovery Step 1 scan).
+
+## Deploy and Verify
+
+1. Run the platform deploy command: `vercel deploy --prod`, `netlify deploy --prod`, `fly deploy`.
+2. If the command requires interactive input, run it and show output to the user.
+3. After deploy, run health checks against the production URL.
+4. Write a deploy-history event recording: platform, project name, deploy URL, commit SHA, timestamp.
+
+## Operations
+
+| Command | Vercel | Netlify | Fly.io |
+|---------|--------|---------|--------|
+| status | `vercel list` | `netlify status` | `fly status` |
+| logs | `vercel logs` | `netlify logs` | `fly logs` |
+| rollback | `vercel rollback` | `netlify rollback` | `fly rollback` |
+| env | `vercel env ls` | `netlify env:list` | `fly secrets list` |
+
+Platform rollback is instant — no release-based rollback needed.
+
+## Platform-Specific Patterns
+
+### Vercel
+
+Vercel auto-detects Next.js projects — no config file required for basic deployments. Generate `vercel.json` only for custom rewrites, redirects, or headers.
+
+Key behaviors:
+- Next.js: framework auto-detected, build command and output directory inferred automatically
+- Static sites: set build command and output directory via `vercel.json` or CLI
+- Env vars: `vercel env add <KEY>` (supports `production`, `preview`, `development` environments)
+- Deploy preview: every branch gets a preview URL automatically (if connected via GitHub)
+
+### Netlify
+
+Netlify requires explicit build and publish configuration. Use `netlify.toml`:
+
+```toml
+[build]
+  command = "npm run build"
+  publish = "dist"
+
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200
+```
+
+Key behaviors:
+- SPA redirects: the catch-all redirect above is essential for client-side routing
+- Env vars: `netlify env:set <KEY> <VALUE>` (per-context: `production`, `deploy-preview`, `branch-deploy`)
+- Branch deploys: every branch gets a deploy-preview URL automatically (if connected via GitHub)
+
+### Fly.io
+
+Fly.io requires a `fly.toml` with app name, builder, and HTTP service config:
+
+```toml
+app = "<app-name>"
+primary_region = "lhr"
+
+[build]
+  builder = "dockerfile"
+
+[http_service]
+  internal_port = 3000
+  force_https = true
+```
+
+Key behaviors:
+- Builder: `dockerfile` (default, uses Dockerfile) or `static` (static site hosting)
+- 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
+
+**Note**: These are minimum-viable platform references; browser-based authentication remains a user-action step. Enriched platform coverage is planned for future iterations.

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

@@ -0,0 +1,147 @@
+# deploy.config.json Schema
+
+This file is the machine-readable deployment configuration. Always read it before executing any deploy operation.
+
+## Top-Level Structure
+
+```json
+{
+  "version": 1,
+  "project": "project-name",
+  "deploymentMode": "ssh",
+  "defaults": { ... },
+  "environments": { ... },
+  "servers": [ ... ],
+  "repository": { ... },
+  "apps": [ ... ],
+  "nginx": { ... },
+  "env": { ... }
+}
+```
+
+## defaults
+
+```json
+{
+  "releaseRetention": 5,
+  "credentialMode": "ai-assisted|user-managed",
+  "secretStorage": "ask-every-time|encrypted-local|plaintext-local|user-managed-on-server-only",
+  "rollbackOnFailure": true,
+  "headlessDefaultEnvironment": "test"
+}
+```
+
+## environments
+
+Keyed by environment name. Each entry:
+```json
+{
+  "dev": {
+    "server": "server-id",
+    "allowHeadless": true,
+    "confirmBeforeDeploy": false
+  }
+}
+```
+
+## servers
+
+Array of server objects:
+```json
+{
+  "id": "prod-1",
+  "host": "IP or hostname",
+  "port": 22,
+  "bootstrapUser": "root",
+  "runtimeUser": "deploy",
+  "roles": ["web"],
+  "validated": {
+    "ssh": true|false,
+    "bootstrap": true|false,
+    "runtimeUser": true|false,
+    "tools": {
+      "node": "version",
+      "npm": "version",
+      "pm2": "version",
+      "nginx": "version",
+      "git": "version"
+    },
+    "directories": true|false,
+    "deployKey": true|false
+  }
+}
+```
+
+## repository
+
+```json
+{
+  "url": "git@github.com:owner/repo.git",
+  "branch": "master",
+  "auth": "deploy-key|ssh-agent|token",
+  "validated": {
+    "clone": true|false
+  }
+}
+```
+
+## apps
+
+Array of app objects:
+```json
+{
+  "id": "web",
+  "path": ".",
+  "runtime": "pm2",
+  "packageManager": "npm",
+  "installCommand": "npm ci",
+  "buildCommand": "npm run build",
+  "startCommand": "npm run start",
+  "ports": {
+    "blue": 3101,
+    "green": 3102
+  },
+  "healthChecks": [
+    { "name": "home", "url": "/", "expectedStatus": [200] },
+    { "name": "login", "url": "/login", "expectedStatus": [200, 302] }
+  ],
+  "activeColor": "blue",
+  "pm2Process": "prizm-ideas-blue"
+}
+```
+
+## nginx
+
+```json
+{
+  "enabled": true,
+  "managed": true,
+  "firstChangeRequiresConfirmation": true,
+  "domain": null,
+  "ipFallback": true,
+  "currentUpstream": "127.0.0.1:3101"
+}
+```
+
+## env
+
+```json
+{
+  "strategy": "ai-assisted|user-managed",
+  "required": ["VAR_NAME"],
+  "secrets": ["SECRET_NAME"],
+  "validated": {
+    "allRequiredPresent": true|false
+  }
+}
+```
+
+## Validation Rules
+
+- `version` must be present (always 1 for first version)
+- `servers` must have at least one entry with host and bootstrapUser
+- `repository.url` must be present
+- `apps` must have at least one entry
+- `apps[*].ports.blue` and `apps[*].ports.green` must differ
+- `apps[*].healthChecks` should have at least one entry
+- Environment referenced in `environments` must have a matching server in `servers`

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

@@ -0,0 +1,62 @@
+# Deploy History Record Schema
+
+Each event in `.prizmkit/deploy/deploy-history/<id>.json` follows this schema:
+
+```json
+{
+  "eventId": "<releaseId or event id>",
+  "eventType": "deploy|rollback|status|validation|failed-deploy|user-aborted|takeover|adapter-gap",
+  "timestamp": "<ISO 8601>",
+  "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>",
+  "previousReleasePath": "<previous release path or null for first deploy>",
+  "targetPort": 3101,
+  "targetColor": "blue|green",
+  "previousPort": 3102,
+  "phases": {
+    "preflight": "success|failed|skipped",
+    "prepareRelease": "success|failed|skipped",
+    "fetchCode": "success|failed|skipped",
+    "installDependencies": "success|failed|skipped",
+    "build": "success|failed|skipped",
+    "stageRuntime": "success|failed|skipped",
+    "healthCheck": "success|failed|skipped",
+    "switchTraffic": "success|failed|skipped",
+    "verifyLive": "success|failed|skipped",
+    "cleanupOldReleases": "success|failed|skipped",
+    "recordHistory": "success|failed|skipped"
+  },
+  "healthCheckResults": [
+    {
+      "name": "home",
+      "url": "/",
+      "expected": [200],
+      "actual": 200,
+      "pass": true
+    }
+  ],
+  "rollbackResult": null,
+  "logPath": "<server log path>",
+  "operatorMode": "ai-assisted|user-managed",
+  "notes": "<human-readable summary of what happened>"
+}
+```
+
+## 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.
+- `rollbackResult`: `null` for non-rollback events, `"success"` or `"failed"` for rollbacks.
+- `notes`: Keep concise but include any anomalies or manual interventions.
+
+## What NOT to record
+
+- Raw secret values or API keys — never.
+- Unsalted hashes of secret values — inferable with rainbow tables.
+- Passphrases or decryption keys — even if hashed.
+- Full environment variable values — presence metadata only (e.g., `{"SUPABASE_KEY": {"present": true}}`).

package/bundled/skills/prizmkit-deploy/references/docker-deploy.md

@@ -0,0 +1,31 @@
+# Docker Deployment Path
+
+Guided deployment when a `Dockerfile` or `docker-compose.yml` is detected, or the user requests Docker deployment.
+
+## Detect and Configure
+
+1. Read `Dockerfile` — extract base image, exposed ports, build steps.
+2. Read `docker-compose.yml` if present — extract services, volumes, environment, ports.
+3. Identify image name: from compose project name or repo directory name.
+4. Identify port mappings: from `EXPOSE`, `ports:` in compose, or ask the user.
+
+## Build and Deploy
+
+1. Build: `docker build -t <project>:<releaseId> .` or `docker compose build`.
+2. Check for running containers with the same name: `docker ps -a --filter name=<project>`.
+3. If a previous container exists:
+   - For blue/green on a server with Nginx: start new container on different port, health check, switch upstream.
+   - For single-container setup: stop old, start new — warn about brief downtime.
+4. Start: `docker run -d --name <project>-<releaseId> -p <port>:<port> <project>:<releaseId>` or `docker compose up -d`.
+5. Health check the new container.
+6. Write deploy-history event.
+
+## Operations
+
+| Command | Docker CLI |
+|---------|-----------|
+| status | `docker ps --filter name=<project>` |
+| logs | `docker logs <container-name> --tail 100` |
+| restart | `docker restart <container-name>` |
+| rollback | `docker stop <new-container> && docker start <old-container>` |
+| cleanup | `docker image prune -a --filter "label=project=<project>"` |

package/bundled/skills/prizmkit-deploy/references/nginx-blue-green.md

@@ -0,0 +1,59 @@
+# Nginx Blue/Green Configuration Template
+
+## Server Block Template
+
+```nginx
+# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY
+upstream <project>_backend {
+    server 127.0.0.1:<activePort>;
+}
+
+server {
+    listen 80 default_server;
+    server_name _;
+
+    # PrizmKit managed marker: <project>
+    location / {
+        proxy_pass http://<project>_backend;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+## Traffic Switch Procedure
+
+When switching from one color to another:
+
+1. Update the `upstream` block: change `server 127.0.0.1:<oldPort>` to `server 127.0.0.1:<newPort>`
+2. Run `nginx -t` to validate syntax
+3. If syntax check passes: `systemctl reload nginx`
+4. If syntax check fails: DO NOT reload. Abort the switch. Report the error.
+
+## Managed Marker
+
+All PrizmKit-generated Nginx config must contain:
+```
+# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY
+```
+
+Before modifying any server block that lacks this marker, ask for user confirmation.
+
+## First-Time Setup
+
+- Disable default nginx site: `rm -f /etc/nginx/sites-enabled/default`
+- Create new config: `/etc/nginx/sites-available/<project>`
+- Symlink: `ln -sf /etc/nginx/sites-available/<project> /etc/nginx/sites-enabled/<project>`
+- Test: `nginx -t`
+- Reload: `systemctl reload nginx`
+
+## Rediscovery of Active Port
+
+If `deploy-metadata.json` is missing, rediscover the active upstream port from Nginx config:
+```
+grep "server 127.0.0.1:" /etc/nginx/sites-available/<project>
+```
+Then match the port against configured blue/green ports to determine active color.

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

@@ -138,7 +138,6 @@ Detect database and deployment signals, then ask 1-2 brief questions. This phase
      - **Target**: [platform name or "undecided"]
      ```
      → This is intentionally minimal (Quick Scan). Full conventions and deployment details will be added by app-planner or prizmkit-deploy later.
-   - Create `.prizmkit/deploy.md` skeleton from `prizmkit-deploy` template if it does not exist, pre-filling known sections (Prerequisites, basic deployment method)
    - If user selects "Skip — decide later" for BOTH topics: write deferred marker instead:
      ```markdown
      ### Infrastructure
@@ -265,7 +264,6 @@ Infrastructure Quick Scan:
   Database: PostgreSQL (Prisma) — detected from dependencies
   Deployment: Vercel — detected from vercel.json
   → Written to CLAUDE.md ### Infrastructure
-  → Created .prizmkit/deploy.md skeleton
 
 Modules discovered:
   src/routes/     → .prizm-docs/routes.prizm (12 files)

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

@@ -68,9 +68,6 @@ A universal spec + plan generator. Takes a natural-language description of ANY d
    - Behavior preservation strategy (if the task modifies existing behavior — include what must remain unchanged and how to verify)
 5. Cross-check: every goal in spec.md maps to plan components — unmapped goals = coverage gaps
 6. Check alignment with `.prizm-docs/root.prizm` RULES section
-7. **Deployment strategy check** (skip if no deployment impact):
-   - Read `.prizmkit/config.json` `deploy_strategy` field
-   - No strategy and new infra needed → ask user, write to config.json
 
 ### Phase 2: Task Generation (plan.md → Tasks section)
 

package/bundled/skills/refactor-pipeline-launcher/SKILL.md

@@ -139,6 +139,13 @@ Detect user intent from their message, then follow the corresponding workflow:
 
 6. **Ask configuration options** ⚠️ MANDATORY INTERACTIVE STEP — applies to ALL execution modes (Foreground, Background, AND Manual). You MUST ask the user to configure options and WAIT for their response BEFORE proceeding to step 7. Do NOT skip this step or merge it with step 7.
 
+   ⛔ **HARD STOP**: You MUST call `AskUserQuestion` with the questions below and WAIT for the user's response. You MUST NOT:
+   - Skip this step and jump to step 7
+   - Merge step 6 and step 7 into one response
+   - Assume default values and show the command without asking
+   - Show the command as text and ask "ready?" without presenting the options
+   If you find yourself writing the final command before the user has answered these questions, STOP — you are violating this rule.
+
    Use `AskUserQuestion` to present the following configuration choices. Each question is a separate selectable option:
 
    **Question 1 — Verbose logging** (multiSelect: false):
@@ -176,6 +183,10 @@ Detect user intent from their message, then follow the corresponding workflow:
    - Off (default) — Skip adversarial review
    - On — Enable adversarial critic review: an independent AI agent reviews the refactor plan for completeness and the implementation for regressions, missed edge cases, and behavior violations. Adds ~5-10 min per refactor task.
 
+   **Question 4 — Deploy after completion?** (multiSelect: false):
+   - No (default) — Skip deployment after pipeline completes
+   - Yes — Run /prizmkit-deploy automatically after all refactors complete successfully (`ENABLE_DEPLOY=1`). Deployment is blocked if any refactor did not complete successfully (status not 'completed' or manually 'skipped').
+
    Default Critic to Off unless refactor items have `priority: "critical"` (in which case default to On).
 
    **Environment variable mapping** (for translating user responses → env vars):
@@ -190,6 +201,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    | Critic: On | `ENABLE_CRITIC=true` |
    | Timeout: value | `SESSION_TIMEOUT=<seconds>` |
    | Stop on failure: On | `STOP_ON_FAILURE=1` |
+   | Deploy: Yes | `ENABLE_DEPLOY=1` |
 
    **Advanced environment variables** (not exposed in interactive menu, pass via `--env`):
 
@@ -214,7 +226,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    ```
    With all options:
    ```bash
-   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 SESSION_TIMEOUT=3600 \
+   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 SESSION_TIMEOUT=3600 ENABLE_DEPLOY=1 \
      dev-pipeline/run-refactor.sh run .prizmkit/plans/refactor-list.json
    ```
 
@@ -225,7 +237,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    With all options:
    ```bash
    dev-pipeline/launch-refactor-daemon.sh start .prizmkit/plans/refactor-list.json \
-     --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5"
+     --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 ENABLE_DEPLOY=1"
    ```
 
    **Manual mode**: Print the assembled command(s) and **stop here**. Do not execute anything. Do not proceed to step 8.
@@ -367,6 +379,7 @@ Notes:
 | All refactors blocked/failed | Show status, suggest recovery: `dev-pipeline/reset-refactor.sh <R-XXX> --clean --run .prizmkit/plans/refactor-list.json` |
 | `playwright-cli` not installed | Browser verification skipped for playwright refactors (non-blocking). Suggest: `npm install -g @playwright/cli@latest && playwright-cli install --skills` |
 | `opencli` not installed | Browser verification skipped for opencli refactors (non-blocking). Install opencli for Chrome session-based browser verification |
+| Deploy session failed | Pipeline completed but deploy session exited non-zero. Check `.prizmkit/state/refactor/deploy/<session_id>/logs/session.log`. Retry manually: `/prizmkit-deploy`. |
 | Permission denied on script | Run `chmod +x dev-pipeline/launch-refactor-daemon.sh dev-pipeline/run-refactor.sh` |
 
 ### Integration Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.40",
+  "version": "1.1.42",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {

package/bundled/dev-pipeline/templates/sections/phase-deploy-verification.md

@@ -1,31 +0,0 @@
-### Local Deploy Verification
-
-You just implemented this feature — you know the project's tech stack and build tools.
-
-1. **Build**: Run the project's build/compile commands. If a required tool is missing, install it first.
-2. **Fix**: If build fails with code errors (type errors, missing imports, config issues), fix them (max 2 rounds), then re-verify.
-3. **Assess and record** — append to context-snapshot.md:
-   - **ALL builds pass** → `## Deploy Verification: PASS` — proceed to commit
-   - **Some builds fail with fixable errors** → fix and re-verify (already handled in step 2)
-   - **Cannot build locally** (missing system-level deps you cannot install) → Record: `## Deploy Verification: PARTIAL — missing system deps (see below)`
-
-Deploy verification does NOT block the commit, but you MUST attempt it.
-
-**Smoke test** (only if build passed and project can be started):
-1. Start the project locally (e.g., `make dev`, `npm start`, `go run .`, etc.)
-2. Verify basic functionality: hit key endpoints, check health routes, confirm the UI loads
-3. Stop the server process you started — do NOT leave it running
-4. Record smoke test results in `## Deploy Verification` section
-
-If the project cannot be started locally (e.g., requires external services, databases, credentials), skip the smoke test and note why.
-
-**Deploy documentation update** — Run `/prizmkit-deploy` ONLY if this feature introduced new infrastructure or deployment-affecting changes:
-- New database, cache, message queue, or external service dependency
-- New environment variables required
-- New build steps or deployment configuration (Dockerfile, CI/CD, cloud config)
-- Changed ports, protocols, or service topology
-
-If none of the above apply (pure application logic change), skip `/prizmkit-deploy`.
-
-
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `deploy-verification` to `"completed"`.