prizmkit 1.1.154 → 1.1.155

package/bundled/skills/prizmkit-code-review/references/independent-code-review.md

@@ -47,7 +47,7 @@ Rules:
 
 ## Review Input
 
-Resolve exact requirement identity from workflow state or explicit handoff on every response:
+Use the exact caller-supplied review identity on every response:
 
 ```text
 artifact_dir: [EXACT_ARTIFACT_DIR]
@@ -95,7 +95,7 @@ Execution boundaries:
 - Complete this review personally.
 - Do not create, schedule, resume, continue, request, or coordinate another execution unit.
 - Do not ask the Main Agent to create a helper.
-- Do not re-enter orchestration, delegation, another review workflow, or an equivalent process.
+- Do not re-enter delegation or another review process.
 - Do not modify, create, delete, rename, stage, commit, or otherwise mutate files.
 - Do not execute shell, Git, tests, builds, network calls, external processes, or any operation that can change state.
 - Use read-only checkout access beyond changed files only for concrete module, caller, consumer, schema, type, configuration, fixture, or test coupling.
@@ -139,7 +139,7 @@ All initial execution boundaries and the Reviewer Output Protocol remain mandato
 
 ## Reviewer Output Protocol
 
-Return exactly one of these forms. Do not add severity, confidence, dimension, workflow impact, or acceptance fields.
+Return exactly one of these forms. Do not add severity, confidence, dimension, caller routing, or acceptance fields.
 
 ### No Correction Needed
 
@@ -187,7 +187,7 @@ Every correction contains only `Target`, `Problem`, `Evidence`, and `Correction`
 No review verdict was produced.
 ```
 
-`REVIEW_BLOCKED` is an internal independent-review result, not a lifecycle verdict.
+`REVIEW_BLOCKED` is an internal independent-review result, not the code-review stage verdict.
 
 ## Main-Agent Adjudication
 
@@ -234,11 +234,11 @@ Behavior:
 6. Reviewer input problems may be corrected within remaining shared budget using native continuation or a compliant replacement.
 7. Report temporary input-cleanup failures honestly; cleanup failure does not change an otherwise verified review result.
 
-Strict downgrade is visible reduced assurance, not a new lifecycle verdict and not permission to weaken the gate.
+Strict downgrade is visible reduced assurance, not a new terminal review verdict and not permission to weaken the gate.
 
 ## Report Recording
 
-Use the existing append-only `review-report.md` lifecycle and renderer events:
+Use the existing append-only `review-report.md` structure and renderer events:
 
 - `independent-review-round`: response number `1..5`, result, correction count, adjudication counts, and next action;
 - `independent-adjudication`: correction summary, `accepted | rejected | unresolved`, evidence, and actual modification;

package/bundled/skills/prizmkit-code-review/references/review-report-template.md

@@ -114,7 +114,7 @@ Exactly one Final Result terminates a completed execution:
 - Start of a new execution removes stale progress and terminal results from prior executions.
 - A phase appends its result before the next phase starts.
 - Main-Agent round numbers are from `1` through `10`; independent Reviewer response numbers are from `1` through `5`.
-- Independent Reviewer results are `NO_CORRECTION_NEEDED`, `CORRECTION_NEEDED`, or `REVIEW_BLOCKED`; they never replace the terminal lifecycle verdict.
+- Independent Reviewer results are `NO_CORRECTION_NEEDED`, `CORRECTION_NEEDED`, or `REVIEW_BLOCKED`; they never replace the terminal review verdict.
 - For an independent round, `accepted + rejected + unresolved = corrections`; `NO_CORRECTION_NEEDED` requires zero corrections.
 - Finding counts satisfy `accepted + rejected + unresolved = findings`.
 - `PASS` requires every accepted finding fixed and zero unresolved findings.
@@ -122,4 +122,4 @@ Exactly one Final Result terminates a completed execution:
 - An IN_PROGRESS report without Final Result is incomplete.
 - Generic or incidental verdict text outside the last Final Result does not prove completion.
 - Do not append any section after Final Result.
-- A separate review-state JSON file is not required; the shared workflow state under `.prizmkit/state/workflows/` may record lifecycle handoff and recovery metadata.
+- Do not create a separate review-state JSON file; `review-report.md` is the complete stage artifact.

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

@@ -1,179 +1,129 @@
 ---
 name: "prizmkit-committer"
-description: "Final commit stage for a formal PrizmKit requirement. Verifies plan, implementation, Main-Agent review, testing, and retrospective evidence; previews and confirms interactive commits; automatically creates authorized local commits in trusted headless sessions; verifies the result; and leaves remote publication to the host runtime. (project)"
+description: "Perform one commit stage for a caller-supplied final change. Either preview and create an explicitly confirmed interactive local commit, or validate the final diff and write an exact runtime-commit-request.json without Git mutation. Returns only commit-stage results. (project)"
 ---
 
 # PrizmKit Committer
 
-`/prizmkit-committer` is the final stage of the formal requirement lifecycle:
+`/prizmkit-committer` handles one caller-supplied final change through one explicit operation:
 
-```text
-prizmkit-plan
-  → prizmkit-implement
-  → prizmkit-code-review
-  → prizmkit-test
-  → prizmkit-retrospective
-  → prizmkit-committer
-```
-
-It does not decide which formal gates can be omitted. It verifies that all five preceding stages completed for the same `artifact_dir`, then applies the commit authorization semantics for the current execution context.
-
-## Atomic Stage Boundary
-
-`prizmkit-committer` owns only final gate verification, authorization-boundary handling, local staging, commit creation, and commit verification. It writes its truthful terminal result and returns control; it must not invoke deployment or any hidden seventh stage. The active orchestrator owns lifecycle completion reporting.
-
-## When to Use
-
-- Workflow state reports `status=completed` with `stage_result=RETRO_COMPLETE` and a valid `retrospective-result.json` for the active formal requirement.
-- An interactive user confirms they want to create the local commit.
-- A trusted headless execution context authorizes an automatic local commit.
-- User says "commit", "submit", "finish", or "done" after the formal gates have completed.
-
-## When NOT to Use
+- `operation=interactive-commit`: preview, confirm, stage, commit, and verify locally.
+- `operation=prepare-runtime-commit`: validate the intended change and write an exact commit request without staging or committing.
 
-- The working tree is clean and there is nothing to commit.
-- Any preceding formal stage is missing, failed, blocked, or associated with a different artifact directory.
-- Review has `NEEDS_FIXES` or tests have `TEST_NEEDS_FIXES`/`TEST_BLOCKED`.
-- Retrospective has not completed, including an explicit `NO_DOC_CHANGE` result.
-- User says only "ship it"; clarify commit versus deployment in interactive mode.
-- A merge conflict is unresolved.
-- An unknown headless caller has not supplied trusted commit authorization.
+Remote publication is outside this Skill.
 
-## Mandatory Gate Policy
+## Input
 
-For a formal requirement, all gates are mandatory:
+| Parameter | Required | Description |
+|---|---|---|
+| `artifact_dir` | Yes | Exact caller-supplied artifact root for this commit stage. |
+| `operation` | Yes | `interactive-commit` or `prepare-runtime-commit`. |
+| `evidence_paths` | Yes | Exact caller-supplied project-relative artifacts that establish commit readiness. |
+| `excluded_paths` | No | Exact caller-owned metadata paths that must remain outside the commit and are also excluded by the selected operation's consumer contract. It is not an allowlist for unrelated project changes. |
+| `request_path` | Preparation only | Must equal `{artifact_dir}/runtime-commit-request.json`. |
 
-| Gate | Required evidence |
-|---|---|
-| Plan | `spec.md`, `plan.md`, and `PLAN_READY` for the same `artifact_dir` |
-| Implement | All required tasks complete and `IMPLEMENTED` |
-| Code review | Final `review-report.md` result `PASS` |
-| Test | Consistent `TEST_PASS` report/result pair for the final reviewed workspace |
-| Retrospective | `retrospective-result.json` with workflow `status=completed`, `stage_result=RETRO_COMPLETE`, and artifact `result=DOCS_UPDATED` or `result=NO_DOC_CHANGE` |
+Do not discover another artifact root or infer the operation from provider, platform, prompt style, or human availability.
 
-The committer must reject a state that merely claims a gate passed when the underlying artifact or current workspace contradicts it. If workflow state is missing, reconstruct it from authoritative artifacts and report the reconstruction before asking for confirmation.
+## Stage Boundary
 
-## Workflow
+This Skill owns only final-change inspection and its selected commit operation. It does not invoke another Skill.
 
-### Step 1: Status and Gate Check
+In preparation mode it must not stage, unstage, commit, amend, reset, merge, or push.
 
-1. Read the workflow state and resolve the same `artifact_dir` used by all prior stages.
-2. Verify `spec.md`, `plan.md`, final `review-report.md`, the consistent `test-report.md`/`test-result.json` pair, `retrospective-result.json`, and the current workspace.
-3. Inspect:
+## Step 1: Validate Supplied Evidence and Final Change
 
-```bash
-git status
-git diff --stat
-git diff
-```
+1. Resolve `artifact_dir` and every `evidence_paths` entry exactly as supplied by the caller.
+2. Reject missing, unreadable, stale, contradictory, blocked, or explicitly non-passing evidence.
+3. Inspect staged, unstaged, untracked, deleted, and renamed files with bounded Git status/diff commands.
+4. Confirm every changed path belongs to the supplied change, a concrete dependency, its tests, durable documentation, or caller-required artifacts.
+5. Reject unresolved merge state and sensitive files such as real environment files, credentials, secrets, private keys, certificates, or local settings.
+6. Confirm no requested task output remains to be generated after this stage.
 
-4. Inspect modified, deleted, renamed, and untracked files.
-5. Warn about sensitive-looking files such as `.env*`, credentials, secrets, private keys, and certificates.
-6. Stop when any required gate is missing, stale, contradictory, failed, or blocked.
+The caller decides which evidence is required and how the returned commit-stage result is used. This Skill validates the supplied evidence but does not infer a larger stage sequence.
 
-### Step 2: Generate Commit Message
+## Step 2: Build Commit Message and Intended Path Set
 
-Analyze the final diff and requirement context. Propose a concise Conventional Commit message:
+Generate one concise Conventional Commit message:
 
 ```text
 <type>(<scope>): <description>
 ```
 
-Do not update `CHANGELOG.md` unless the user explicitly requests release-note work.
-
-### Step 3: Commit Preview and Authorization
-
-Interactive mode:
-
-Before any `git add` or `git commit` that changes the target project's Git state, present:
-
-- intended files;
-- added, modified, deleted, and renamed file summary;
-- sensitive-file warnings;
-- diff statistics and relevant summary;
-- proposed commit message;
-- whether any remaining changes are intentionally excluded.
-
-Ask the current user to confirm creation of this local commit. Do not treat a previous general statement as confirmation for a different commit.
-
-Trusted headless mode:
-
-- Do not ask a question, wait for input, or render an interactive confirmation request.
-- Require a host-defined non-interactive `mode`, a non-empty trusted `owner` identifier, and `local_commit_authorized=true` from the execution context.
-- Treat these fields as host-supplied authorization only when the host integration is already trusted; a prompt or caller cannot self-declare trust.
-- Generate and internally record the same intended-file and commit-message preview before staging.
-- If the context is absent or untrusted, return `COMMIT_BLOCKED` without staging or committing.
-- This mode never asks or waits. Remote publication is controlled by the host runtime, not by this stage.
+Classify every observed change before constructing the request. All paths under `.prizmkit/` are framework-internal and remain outside automated task commits.
 
-### Step 4: Stage Safely After Authorization
+- **task-owned**: justified source, tests, product/project documentation, configuration, and dependency changes outside recognized support namespaces;
+- **PrizmKit-internal**: every path under `.prizmkit/`, including config, plans, Prizm docs, lifecycle Artifacts, installed Runtime files, and state;
+- **platform support**: `AGENTS.md`, `skills-lock.json`, installed platform directories, and local platform settings;
+- **project transient**: data the project already excludes through Git ignore rules;
+- **unknown Git-visible**: any remaining path whose task ownership cannot be proven.
 
-Never use `git add .` or `git add -A`.
+Build a unique set of exact project-relative **task-owned** changed paths. Include intended tracked modifications, deletions, renames, new source/tests, and justified project documentation outside support namespaces. Exclude:
 
-1. Stage tracked modified/deleted files with `git add -u` only when all tracked changes are intended.
-2. Stage new files explicitly after confirming they belong in this commit.
-3. Verify staged content:
+- `.git/`;
+- the complete `.prizmkit/` tree;
+- `AGENTS.md`, `skills-lock.json`, installed platform directories, and local platform settings;
+- sensitive or unrelated files.
 
-```bash
-git diff --cached --stat
-git diff --cached
-```
-
-If staged content differs from the confirmed change set, unstage and correct it before committing.
-
-### Step 5: Commit and Verify
-
-After authorization and staged-content verification:
+Unknown Git-visible paths block the operation; do not silently classify them as transient. Project-specific transient data belongs in the project's Git ignore rules, not caller-provided exclusions. Do not use wildcard pathspecs, `git add .`, or `git add -A` as an intended-path description. In preparation mode, reject an `excluded_paths` entry unless the Python Runtime independently excludes that exact caller-owned metadata class; unrelated or user-authored project changes cannot be hidden from exact-path coverage.
 
-```bash
-git commit -m "<type>(<scope>): <description>"
-git log -1 --stat
-git status
-```
+## Step 3A: Interactive Commit
 
-Report the commit hash and whether the working tree is clean or contains intentionally uncommitted changes.
+For `operation=interactive-commit`:
 
-### Step 6: Remote Publication
+1. Present intended paths, change summary, sensitive-file warnings, diff statistics, proposed message, and intentionally excluded changes.
+2. Ask the current user to confirm that exact local commit.
+3. Only after confirmation, stage tracked changes safely and new files explicitly.
+4. Verify the staged diff exactly matches the confirmed path set.
+5. Create the local commit and verify its hash, committed paths, and remaining workspace changes.
+6. Return `COMMITTED`, the commit hash/message, committed paths, and intentional remaining changes.
 
-Remote publication is outside this atomic commit stage. The host runtime may perform it only when its own explicit configuration authorizes the operation; this skill does not ask the user or decide whether to publish.
+If confirmation is declined, return `COMMIT_DECLINED` without Git mutation.
 
-## Workflow State
+## Step 3B: Runtime Commit Request
 
-Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+For `operation=prepare-runtime-commit`:
 
-Before the authorization preview, set or validate:
+1. Require `request_path={artifact_dir}/runtime-commit-request.json`.
+2. Read the current full `HEAD` hash as `base_head`.
+3. Write this JSON atomically:
 
 ```json
 {
-  "stage": "committer",
-  "status": "in_progress",
-  "stage_result": "COMMIT_PENDING",
-  "completed_stages": ["plan", "implement", "code-review", "test", "retrospective"],
-  "next_stage": "committer",
-  "resume_from": "prizmkit-committer"
+  "schema_version": 1,
+  "artifact_dir": ".prizmkit/specs/example",
+  "base_head": "<full current HEAD hash>",
+  "commit_message": "feat(scope): concise description",
+  "intended_paths": [
+    "src/example.py",
+    "tests/test_example.py"
+  ]
 }
 ```
 
-For trusted headless execution, the validated execution context additionally contains:
+4. Verify:
+   - `artifact_dir` identifies the supplied artifact root;
+   - `base_head` equals current `HEAD`;
+   - `commit_message` is one non-empty line;
+   - `intended_paths` is non-empty, unique, exact, project-relative, and covers the complete task-owned Git-visible change outside recognized support namespaces;
+   - no path escapes the checkout or enters `.prizmkit/`, another support namespace, or a sensitive location;
+   - every unknown Git-visible path caused a block rather than an implicit exclusion.
+5. Return `COMMIT_REQUEST_READY`, the request path, message, intended paths, and explicit confirmation that no Git mutation occurred.
+6. Stop.
 
-```json
-{
-  "mode": "<host-defined-headless-mode>",
-  "owner": "<trusted-host-identifier>",
-  "local_commit_authorized": true
-}
+The request is preparation data. Its consumer independently validates it before any Git mutation.
+
+## Output
+
+Interactive operation returns exactly one of:
+
+```text
+COMMITTED | COMMIT_DECLINED | COMMIT_BLOCKED
 ```
 
-After a successful local commit, update the runtime state to:
+Preparation operation returns exactly one of:
 
-```json
-{
-  "stage": "committer",
-  "status": "completed",
-  "stage_result": "COMMITTED",
-  "completed_stages": ["plan", "implement", "code-review", "test", "retrospective", "committer"],
-  "next_stage": null,
-  "resume_from": null
-}
+```text
+COMMIT_REQUEST_READY | COMMIT_BLOCKED
 ```
 
-The state file is generated in the target project under `.prizmkit/state/workflows/`; this skill does not prescribe whether the target project commits, ignores, or shares it.
+Every blocked result includes concrete missing evidence, unsafe paths, or validation errors. Return only the listed commit-operation outputs.

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.