prizmkit 1.1.153 → 1.1.155

package/bundled/skills/prizmkit-deploy/references/pending-input-schema.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PrizmKit Deployment Pending Input",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "result",
+    "operation",
+    "environment",
+    "known_context",
+    "questions"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "result": {
+      "const": "NEEDS_INPUT"
+    },
+    "operation": {
+      "enum": [
+        "configure",
+        "deploy",
+        "status",
+        "logs",
+        "restart",
+        "rollback",
+        "health",
+        "history",
+        "validate"
+      ]
+    },
+    "environment": {
+      "enum": ["dev", "test", null]
+    },
+    "known_context": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["project_type", "target", "config_path"],
+      "properties": {
+        "project_type": {
+          "type": ["string", "null"]
+        },
+        "target": {
+          "type": ["string", "null"]
+        },
+        "config_path": {
+          "const": ".prizmkit/deploy/deploy.config.json"
+        }
+      }
+    },
+    "questions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "prompt",
+          "answer_type",
+          "required",
+          "config_pointer",
+          "options"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]{0,63}$"
+          },
+          "prompt": {
+            "type": "string",
+            "minLength": 1
+          },
+          "answer_type": {
+            "enum": ["text", "single_choice", "multi_choice", "boolean", "integer"]
+          },
+          "required": {
+            "type": "boolean"
+          },
+          "config_pointer": {
+            "type": "string",
+            "pattern": "^/(?:[^~/]|~[01])+(?:/(?:[^~/]|~[01])*)*$"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["value", "label"],
+              "properties": {
+                "value": {
+                  "type": ["string", "number", "boolean"]
+                },
+                "label": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "answer_type": {
+                  "enum": ["single_choice", "multi_choice"]
+                }
+              }
+            },
+            "then": {
+              "properties": {
+                "options": {
+                  "minItems": 1
+                }
+              }
+            },
+            "else": {
+              "properties": {
+                "options": {
+                  "maxItems": 0
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "examples": [
+    {
+      "schema_version": 1,
+      "result": "NEEDS_INPUT",
+      "operation": "configure",
+      "environment": null,
+      "known_context": {
+        "project_type": "Node.js",
+        "target": null,
+        "config_path": ".prizmkit/deploy/deploy.config.json"
+      },
+      "questions": [
+        {
+          "id": "deployment_target",
+          "prompt": "Which deployment target should this project use?",
+          "answer_type": "single_choice",
+          "required": true,
+          "config_pointer": "/deploymentMode",
+          "options": [
+            {
+              "value": "ssh",
+              "label": "SSH Linux server"
+            },
+            {
+              "value": "docker",
+              "label": "Docker"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/bundled/skills/prizmkit-deploy/references/ssh-adapter-flow.md

@@ -47,7 +47,7 @@ Server-side layout:
   deploy-logs/
 ```
 
-`shared/.env.production` must be mode `600` and owned by the runtime user.
+`shared/.env.production` is strict UTF-8 dotenv data with one unique `KEY=value` assignment per line; update it atomically, keep mode `600`, and require runtime-user ownership. `shared/deploy-metadata.json` must conform to `${SKILL_DIR}/references/deploy-metadata-schema.json`, be written atomically after successful live verification, and contain no secrets.
 
 ## 3. First-Run Configuration Wizard
 
@@ -59,7 +59,7 @@ Collect:
 2. Repository access only for `ci-cd-pull`: Git URL, branch, deploy-key or other auth.
 3. App configuration: app id, path, package manager, install/build/start commands, blue/green port pair, health checks.
 4. Environment variables: scan source for env references, ask for values or storage strategy.
-5. Persist `deploy.config.json` and `deploy.md`.
+5. Persist `deploy.config.json` and render/update `deploy.md` from `${SKILL_DIR}/assets/deploy-document-template.md`.
 
 Validate SSH immediately with a harmless connectivity command before collecting deeper config. If SSH fails, stop and fix connectivity first.
 
@@ -132,7 +132,7 @@ Failure rules:
 ## 8. Blue/Green PM2 + Nginx Invariants
 
 - Default ports: blue `3101`, green `3102`.
-- Active color is persisted in `shared/deploy-metadata.json`.
+- Active color is persisted in `shared/deploy-metadata.json` using `${SKILL_DIR}/references/deploy-metadata-schema.json`.
 - PM2 process name: `<project>-<app>-<color>`.
 - Nginx managed blocks include `# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY`.
 - First creation or modification of non-PrizmKit Nginx config requires user confirmation.
@@ -157,8 +157,9 @@ Steps:
 3. Start PM2 on the target release/port.
 4. Update Nginx upstream.
 5. Run `nginx -t` and reload.
-6. Run health checks.
-7. Write rollback event.
+6. Run public health checks; if they fail, restore the prior verified upstream.
+7. Allocate and atomically write the rollback history event through `${SKILL_DIR}/references/deploy-history-schema.md`.
+8. Atomically update `shared/deploy-metadata.json` through `${SKILL_DIR}/references/deploy-metadata-schema.json` with the restored release/color/port and rollback event identity.
 
 If no previous release exists, state clearly that rollback is not possible.
 
@@ -177,13 +178,13 @@ Run app commands as `runtimeUser`.
 Supported storage modes:
 
 - `ask-every-time`
-- `encrypted-local`
-- `plaintext-local`
+- `ignored-local-env`
 - `user-managed-on-server-only`
 
 Rules:
 
-- `plaintext-local` must be gitignored; stop if tracked by git.
+- `ignored-local-env` uses `.prizmkit/deploy/secrets.local.env`, must be ignored by Git and current-user-only, and follows `${SKILL_DIR}/references/database-setup.md` dotenv/migration safety.
+- Legacy `plaintext-local` requires explicit migration to `ignored-local-env`; legacy `encrypted-local` is unsupported and requires user selection of a supported mode before deployment.
 - Server runtime secrets live in `shared/.env.production` with mode `600`.
 - Deploy history records secret presence metadata only.
 - Never record raw secret values, passphrases, decryption keys, or unsalted hashes.

package/bundled/skills/prizmkit-deploy/references/ssh-execution-flow.md

@@ -9,7 +9,7 @@ Show what will be deployed using `git log --oneline <last-deployed-commit>..HEAD
 ## Group 1 — Pre-flight & Prepare
 
 - Verify SSH, runtime user, tools, deploy key, port availability.
-- Generate `releaseId`: `YYYYMMDD-<short-commit-sha>`. Create `releases/<releaseId>`.
+- Generate `releaseId`: `YYYYMMDDTHHMMSSZ-<short-commit-sha>` in UTC. If that release directory already exists, select the lowest free suffix from `-01` through `-99`; never reuse or overwrite a release directory, and stop if the suffix space is exhausted. Create `releases/<releaseId>`.
 - Determine target color: read `activeColor` from `shared/deploy-metadata.json` and use the opposite. If first deploy (no metadata, no `current` symlink), default to blue (port 3101).
 
 ## Group 2 — Fetch & Build
@@ -28,14 +28,14 @@ Show what will be deployed using `git log --oneline <last-deployed-commit>..HEAD
 
 - Update Nginx upstream to new port. Run `nginx -t` — abort on failure.
 - `systemctl reload nginx`. Update `current` symlink to new release.
-- Write `shared/deploy-metadata.json` with new `activeColor`, `activePort`, `lastReleaseId`.
-- Run health checks against public endpoint. If any fails: rollback immediately.
+- Run health checks against the public endpoint. If any fails, rollback immediately and do not record the candidate as active.
 
 ## Group 5 — Cleanup & Record
 
-- Stop old PM2 process. Remove oldest releases beyond `releaseRetention` count. `pm2 save`.
-- Write deploy-history JSON. Update `deploy.config.json` validation status.
+- Allocate the collision-safe deploy event ID and atomically write deploy-history JSON using `${SKILL_DIR}/references/deploy-history-schema.md`, with event identity separate from `releaseId`.
+- After the history record succeeds, atomically write `shared/deploy-metadata.json` from `${SKILL_DIR}/references/deploy-metadata-schema.json` with the verified `activeColor`, `activePort`, `lastReleaseId`, operation event ID, and UTC update time. If either record write fails, preserve both processes/releases, report a recording failure, and require the next operation to rediscover active state from Nginx plus the `current` symlink before retrying metadata repair.
+- Stop the old PM2 process. Remove oldest releases beyond `releaseRetention` count. Run `pm2 save` and update `deploy.config.json` validation status.
 
 ## Post-deploy — Completion Summary
 
-Output a summary (project, URL, version, duration, health status) and append to deploy.md. If `deployStrategy` is `"direct-upload"`, offer CI/CD upgrade (see §SSH: Post-Deploy CI/CD Upgrade).
+Output a summary (project, URL, version, duration, health status) and update the matching sections of `deploy.md` from `${SKILL_DIR}/assets/deploy-document-template.md`; do not append duplicate headings or an event log. If `deployStrategy` is `"direct-upload"`, offer CI/CD upgrade (see §SSH: Post-Deploy CI/CD Upgrade).

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

@@ -1,35 +1,34 @@
 ---
 name: "prizmkit-implement"
-description: "Execute the reviewed plan for a formal PrizmKit requirement, update task checkpoints, preserve the shared workflow artifact directory, and hand off to prizmkit-code-review. Use after prizmkit-plan or when resuming implementation repair. (project)"
+description: "Execute one caller-supplied spec.md/plan.md change, including explicitly scoped repairs, focused verification, and task-marker updates. Returns IMPLEMENTED or IMPLEMENT_BLOCKED. (project)"
 ---
 
 # PrizmKit Implement
 
-`/prizmkit-implement` executes the tasks in one formal requirement's `plan.md`. It is the implementation stage, including implementation repairs requested by code review or testing.
+`/prizmkit-implement` executes tasks from one caller-supplied `plan.md`, including concrete repair findings explicitly included in the request.
 
 ## When to Use
 
-- After `/prizmkit-plan` reports `PLAN_READY`.
-- When workflow state routes a review or test repair back to implementation.
-- When `plan.md` contains unchecked tasks for the active requirement.
+- A caller supplies reviewed `spec.md` and `plan.md` artifacts with incomplete tasks.
+- A caller supplies an explicit repair scope and findings for implementation repair.
+- `plan.md` contains unchecked or explicitly reopened tasks, or the caller requests validation of completed task markers against the current change.
 - User says "implement", "build", "code it", "start coding", "develop", or "execute".
 
 ## When NOT to Use
 
-- No `spec.md` and `plan.md` exist for the formal requirement.
-- All planned tasks are complete and no repair scope is recorded.
+- No `spec.md` and `plan.md` exist for the supplied change.
+- All planned tasks are complete and the caller already has a valid implementation result for the unchanged current work.
 - The user is still deciding scope or asking for planning.
-- The request is a direct low-risk edit outside the formal requirement lifecycle.
+- The request has no reviewed implementation artifact and does not need a formal plan.
 
 ## Preconditions and Artifact Identity
 
 | Required artifact | Check | If missing |
 |---|---|---|
-| `plan.md` with Tasks | Exists and contains incomplete or explicitly repairable work | Return `IMPLEMENT_BLOCKED` and direct the user to `/prizmkit-plan`. |
-| `spec.md` | Exists in the same artifact directory | Return `IMPLEMENT_BLOCKED` and direct the user to `/prizmkit-plan`. |
-| Workflow state | Reusable or reconstructable | Reconstruct from artifacts and report the result when absent or stale. |
+| `plan.md` with Tasks | Exists; contains incomplete/repairable work or completed markers requiring current-change validation | Return `IMPLEMENT_BLOCKED` with the missing-input reason. |
+| `spec.md` | Exists in the same artifact directory | Return `IMPLEMENT_BLOCKED` with the missing-input reason. |
 
-Accept `artifact_dir` from the preceding skill or workflow state. Do not scan for a different most-recent plan when invoked as a handoff. A single requirement must reuse the same `artifact_dir` throughout all stages.
+Require the caller to supply or confirm `artifact_dir`. Do not discover a different recent artifact. Optional repair input must include the exact findings and `repair_scope`; do not infer them from caller state.
 
 ## Context Loading
 
@@ -37,17 +36,17 @@ Before editing:
 
 1. Read `plan.md`, `spec.md`, and only relevant companion artifacts.
 2. Read `.prizmkit/prizm-docs/root.prizm` when present.
-3. Read relevant L1 docs and relevant L2 docs when present.
-4. If an affected L2 doc is missing, read the target source files as fallback and record that no L2 context was available. Do not create L2 merely because it was read; retrospective decides whether durable knowledge warrants it.
+3. Follow its pointers to only the relevant module and detail documentation.
+4. If relevant detail documentation is missing, read the target source files as fallback and record that detailed context was unavailable. Context loading does not create or modify documentation.
 5. Read referenced layer rules when present. If a rule conflicts with the plan, stop and ask the user unless the plan clearly supersedes the rule.
 
 ## Optional Inline Delegation
 
-The default is direct Main-Agent implementation. If a narrow slice is delegated, use `prompt_reference: ${SKILL_DIR}/references/implementation-subagent-procedure.md` and follow its active-checkout/no-worktree constraints. Delegation is optional implementation detail and does not alter lifecycle handoff or ownership.
+The default is direct Main-Agent implementation. If a narrow slice is delegated, use `prompt_reference: ${SKILL_DIR}/references/implementation-subagent-procedure.md` and follow its active-checkout/no-worktree constraints. Delegation is an implementation-stage detail and does not change this Skill's output contract.
 
 ## Atomic Stage Boundary
 
-`prizmkit-implement` owns only execution of plan tasks and implementation repairs. It writes its truthful terminal result and `next_stage`, then returns control. When an external orchestrator is active, it must not invoke code review or test itself. The active orchestrator owns the next-stage invocation.
+`prizmkit-implement` owns only execution of supplied plan tasks and explicitly scoped implementation repairs. It returns `IMPLEMENTED` or `IMPLEMENT_BLOCKED` and stops.
 
 ## Execution
 
@@ -61,15 +60,15 @@ For each unchecked or explicitly repair-scoped task, in plan order:
 4. Avoid unrelated edits and preserve the requirement's artifact identity.
 5. Mark a task complete immediately after its implementation is complete.
 6. Stop dependent tasks on failure; run `[P]` tasks in parallel only when safe.
-7. Execute only local implementation verification here. The mandatory full lifecycle code review follows implementation and the mandatory auditable test stage follows code review.
+7. Execute focused implementation verification appropriate to the changed task; do not expand into a separate broad audit unrelated to implementation.
 
 ### Repair Scope
 
-When routed from a failed test or review, read `repair_scope` from workflow state and constrain edits accordingly:
+When the caller requests repair, require an explicit `repair_scope` and concrete findings:
 
-- `production`, `runtime`, `schema`, `dependency`, or `public-interface`: production-affecting changes. Completion must hand off to `prizmkit-code-review`.
-- `test-infrastructure`: tests, fixtures, test runner configuration, or evidence setup only. Completion may hand off directly to `prizmkit-test`.
-- `unknown`: stop and ask the user; do not guess which downstream gates can be skipped.
+- `production`, `runtime`, `schema`, `dependency`, or `public-interface`: constrain edits to the supplied production concern.
+- `test-infrastructure`: constrain edits to tests, fixtures, runner configuration, or evidence setup.
+- missing or `unknown`: return `IMPLEMENT_BLOCKED`; do not guess the intended repair.
 
 ## Recovery
 
@@ -77,53 +76,18 @@ If interrupted:
 
 - Reuse completed task markers and the same `artifact_dir`.
 - Inspect any partially edited files before continuing.
-- Reconcile workflow state with the plan and current diff.
-- Never report `IMPLEMENTED` when incomplete tasks or unresolved repair work remain.
+- Reconcile plan task markers with the current diff.
+- Never report `IMPLEMENTED` when tasks or supplied repair findings remain unresolved.
 
-## Workflow State
+## Output
 
-Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
-
-On successful implementation, update `.prizmkit/state/workflows/<requirement-slug>.json` with:
-
-```json
-{
-  "stage": "implement",
-  "status": "completed",
-  "stage_result": "IMPLEMENTED",
-  "completed_stages": ["plan", "implement"],
-  "repair_round": 0,
-  "repair_scope": null,
-  "next_stage": "code-review",
-  "resume_from": "prizmkit-code-review"
-}
-```
-
-For a repair, increment `repair_round`, set `status=failed` and `stage_result=IMPLEMENT_REPAIR`, preserve the triggering failure in the state, and select the next stage according to `repair_scope`. The outer workflow permits at most three repair rounds; the implementation stage must return a blocked result rather than start a fourth round.
-
-## Output and Handoff
-
-Report:
+Return only implementation-stage outputs:
 
+- `artifact_dir`;
 - implementation summary;
-- completed and remaining tasks;
-- files changed;
-- local verification performed;
-- workflow state path and status;
-- exact next stage.
-
-On initial implementation or a production-affecting repair:
-
-```text
-IMPLEMENTED
-  → /prizmkit-code-review
-```
-
-On a test-infrastructure-only repair:
-
-```text
-IMPLEMENTED
-  → /prizmkit-test
-```
+- completed and remaining task markers;
+- changed paths;
+- focused verification performed;
+- `IMPLEMENTED` when all supplied work is complete, otherwise `IMPLEMENT_BLOCKED` with exact blockers.
 
-If workflow state names an active `orchestrator`, return the terminal result, state path, and selected next stage to it; do not invoke another stage independently. For direct stage use, provide the deterministic next invocation with the same `artifact_dir`; a host may perform that semantic handoff on the user's behalf.
+Return only the listed implementation outputs. Do not invoke another Skill.

package/bundled/skills/prizmkit-implement/references/implementation-subagent-procedure.md

@@ -29,8 +29,8 @@ Do not create worktrees, copied repositories, remote checkouts, or branch switch
 1. Read `context-snapshot.md` first when it exists.
 2. Use Section 3 for relevant Prizm rules/traps and Section 4 File Manifest for file summaries.
 3. Do not re-read files already summarized in the File Manifest unless a specific implementation detail is missing.
-4. If no context snapshot exists, read `.prizmkit/prizm-docs/root.prizm`, relevant L1/L2 docs, then targeted source files.
-5. If a relevant L2 doc is missing, use source fallback and note that retrospective may create or update docs later.
+4. If no context snapshot exists, read `.prizmkit/prizm-docs/root.prizm`, follow only relevant module/detail pointers, then read targeted source files.
+5. If relevant detail documentation is missing, use source fallback and note the missing context without creating documentation.
 
 ## Implementation Rules
 
@@ -41,7 +41,7 @@ Do not create worktrees, copied repositories, remote checkouts, or branch switch
 - Do not execute git `add`, `commit`, `reset`, `push`, branch checkout, rebase, merge, or stash operations.
 - Do not spawn further agents.
 - Do not perform broad repository rediscovery. Read only delegated files and targeted dependencies needed for correctness.
-- Do not write PrizmKit feature/bug/refactor/task/session/run IDs, pipeline IDs, workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths into `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or expected product-copy tests.
+- Do not write internal execution IDs, branch names, absolute worktree paths, or runtime artifact paths into `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or expected product-copy tests.
 - If creating a new sub-module, note the durable facts needed for retrospective; do not overwrite existing `.prizmkit/prizm-docs/` files in full.
 
 ## Output Format
@@ -61,7 +61,7 @@ Report exactly:
 - command/check: result
 
 ### Notes for Main Agent
-- durable decisions, missing L2 docs, or blockers
+- durable decisions, missing detail documentation, or blockers
 ```
 
 For `WRONG_CHECKOUT`, include only the checkout mismatch evidence and do not include normal implementation findings.

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

@@ -23,6 +23,10 @@ Recommended project initialization skill. Scans any brownfield or greenfield pro
 - If artifacts already exist: idempotent status check offers regenerate/skip choices (see Phase 3: Idempotent Status Check)
 - If no source files found in any directory: fall back to greenfield mode
 
+### Artifact Ownership
+
+All paths under `.prizmkit/` are framework-internal and remain outside automated task commits. Initialization must not stage or commit them. Root instruction or platform-support files written during setup also remain support data rather than task-owned source.
+
 ## Execution Steps
 
 **Phase 1: Platform Detection**

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

@@ -1,11 +1,11 @@
 ---
 name: "prizmkit-plan"
-description: "Start the formal PrizmKit requirement lifecycle by turning a natural-language change into spec.md and plan.md artifacts, running mandatory Main-Agent planning review plus optional capability-gated independent correctness review, initializing workflow state, and handing off to prizmkit-implement. Works for features, bug fixes, refactors, migrations, tests, and other formal requirements. (project)"
+description: "Create and review spec.md and plan.md artifacts for one supplied software requirement. Covers features, bug fixes, refactors, migrations, tests, and other scoped changes; returns PLAN_READY or PLAN_BLOCKED. (project)"
 ---
 
 # PrizmKit Plan
 
-`/prizmkit-plan` is the entry point for one formal requirement. It converts a natural-language change into a reviewed change artifact: `spec.md` defines WHAT and WHY; `plan.md` defines HOW and executable tasks.
+`/prizmkit-plan` converts one caller-supplied natural-language change into a reviewed change artifact: `spec.md` defines WHAT and WHY; `plan.md` defines HOW and executable tasks.
 
 A change artifact can describe a feature, bug fix, refactor, migration, test improvement, or another scoped requirement.
 
@@ -19,47 +19,34 @@ A change artifact can describe a feature, bug fix, refactor, migration, test imp
 ## When NOT to Use
 
 - Direct edit: typo, pure formatting, small documentation edit, or another explicitly low-risk non-requirement change.
-- The active artifact directory already has an adequate reviewed `spec.md` and `plan.md`; resume from the workflow state instead.
-
-## Formal Lifecycle
-
-A successful plan starts this fixed lifecycle:
-
-```text
-plan → implement → code-review → test → retrospective → committer
-```
-
-Planning depth may be concise or comprehensive, but no later formal lifecycle stage may be silently skipped.
+- The supplied artifact directory already has an adequate reviewed `spec.md` and `plan.md`; return the existing stage result instead of regenerating them.
 
 ## Input
 
 | Parameter | Required | Description |
 |---|---|---|
 | `description` | Yes | Natural-language description of the requirement. |
-| `artifact_dir` | No | Directory for the change artifact. If omitted, create a numbered slug under `.prizmkit/specs/`. |
+| `artifact_dir` | No | Exact caller-supplied directory for the change artifact. If omitted, create a deterministic numbered directory under `.prizmkit/specs/` using `${SKILL_DIR}/references/artifact-identity.md`. |
 
 ## Atomic Stage Boundary
 
-`prizmkit-plan` owns only specification, plan, task generation, and planning-quality review. It writes its truthful terminal result and `next_stage`, then returns control. It must not invoke `prizmkit-implement` itself, including when an external orchestrator is active. The active orchestrator owns the next-stage invocation.
+`prizmkit-plan` owns specification, plan, task generation, and planning-quality review for one supplied requirement. Its terminal outputs are `PLAN_READY` or `PLAN_BLOCKED`; it stops after producing that result.
 
 ## Phase 0: Initialization Check and Context
 
 1. Check whether project context such as `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json`, or a project brief exists.
-2. If initialization context is missing:
-   - recommend `/prizmkit-init` and explain that it improves project context and cross-session continuity;
-   - do not block planning;
-   - if the user continues, load the README, manifests, project instruction files, source structure, and relevant source files as fallback.
-3. If Prizm docs exist, read `root.prizm`, relevant L1 docs, relevant L2 docs when present, and source fallback when L2 is absent.
-4. Resolve `artifact_dir` once and reuse it for every later lifecycle handoff. Do not re-detect another artifact during the same requirement.
+2. If initialization context is missing, do not block planning; load the README, manifests, project instruction files, source structure, and relevant source files as fallback.
+3. If Prizm docs exist, read `root.prizm`, follow only its relevant module/detail pointers, and use source fallback when detailed documentation is absent.
+4. Read `${SKILL_DIR}/references/artifact-identity.md`, validate or generate `artifact_dir` exactly once, and keep it stable throughout this planning invocation.
 
 ## Phase 1: Specify (`spec.md`)
 
 Skip regeneration when `spec.md` already exists and still matches the requested requirement.
 
 1. Gather the requirement description. If it is missing in an interactive run, ask the user; otherwise return a clear blocked result.
-2. Determine the artifact directory:
-   - use the caller-provided `artifact_dir` when present;
-   - otherwise scan `.prizmkit/specs/` for existing numbered directories and create `.prizmkit/specs/###-task-slug/`.
+2. Determine the artifact directory through `${SKILL_DIR}/references/artifact-identity.md`:
+   - validate and preserve the exact caller-provided `artifact_dir` when present;
+   - otherwise derive the normalized title slug, allocate the next collision-safe number, and create `.prizmkit/specs/<number>-<slug>/`.
 3. Generate `spec.md` from `${SKILL_DIR}/assets/spec-template.md`:
    - focus on WHAT and WHY, not HOW;
    - include only relevant sections;
@@ -86,7 +73,7 @@ Precondition: `spec.md` exists with no unresolved blocker.
    - component and file changes;
    - data migration approach when relevant;
    - interface/API contract design when relevant;
-   - test strategy for the mandatory `/prizmkit-test` stage;
+   - project-native test strategy appropriate to the requirement;
    - risks and mitigations;
    - behavior-preservation strategy for refactors.
 5. Cross-check every spec goal against the plan.
@@ -98,7 +85,7 @@ Precondition: `spec.md` exists with no unresolved blocker.
 2. Append `## Tasks` to `plan.md` using `${SKILL_DIR}/assets/plan-template.md`.
 3. Include setup, foundation, core, polish, and checkpoint tasks only when applicable.
 4. Mark `[P]` only for tasks that can safely execute independently.
-5. Include implementation-local verification where useful, while preserving the later full code-review and test stages.
+5. Include appropriate implementation-local and regression verification tasks without executing them during planning.
 6. Run `${SKILL_DIR}/references/verification-checklist.md` and repair plan defects.
 
 ## Phase 4: Plan/Spec Review Loop
@@ -113,7 +100,7 @@ Run every time `spec.md` or `plan.md` is created or changed. This is the mandato
 6. If a `BLOCKER` remains, ask targeted questions in interactive mode; otherwise record `PLAN_BLOCKED` and stop.
 7. Continue only when no unresolved blocker remains.
 
-The planning review must not implement code, run the full test stage, or launch external orchestration.
+The planning review must not modify product/source code or execute the planned verification strategy.
 
 ## Phase 5: Independent Plan Review
 
@@ -127,47 +114,17 @@ Run only after the Main-Agent Plan/Spec review converges. This optional check ne
 6. If neither compliant continuation nor replacement is available after modification, record downgrade and rerun the Main-Agent local Plan/Spec review over that modification as specified by the reference.
 7. If the final allowed response causes a modification, run targeted verification, record that the final state was not independently rechecked, and do not exceed the response budget.
 8. Append the terminal `## Independent Plan Review` record. Appending that audit record does not trigger another response.
-9. Any unresolved correction produces `PLAN_BLOCKED`; otherwise independent convergence or strict downgrade may continue to handoff from the valid completed Main-Agent review.
-
-## Phase 6: Workflow State and Handoff
-
-Read `${SKILL_DIR}/references/workflow-state-protocol.md` and create or update:
-
-```text
-.prizmkit/state/workflows/<requirement-slug>.json
-```
-
-Follow the bundled protocol. At minimum record:
-
-```json
-{
-  "schema_version": 1,
-  "artifact_dir": ".prizmkit/specs/001-example",
-  "stage": "plan",
-  "status": "completed",
-  "stage_result": "PLAN_READY",
-  "completed_stages": ["plan"],
-  "repair_round": 0,
-  "repair_scope": null,
-  "next_stage": "implement",
-  "resume_from": "prizmkit-implement"
-}
-```
-
-The state file is runtime metadata. Do not change the target project's Git or ignore policy.
+9. Any unresolved correction produces `PLAN_BLOCKED`; otherwise independent convergence or strict downgrade produces `PLAN_READY`.
 
 ## Output
 
-- `spec.md` and `plan.md` in the resolved artifact directory.
-- Workflow state with `PLAN_READY` or a truthful blocked result.
-- Planning depth, key decisions, task count, and checkpoint summary.
-- The same `artifact_dir` for every downstream stage.
-
-## Handoff
+Return only planning-stage outputs:
 
-On `PLAN_READY`:
+- the resolved `artifact_dir`;
+- `spec.md` and `plan.md` paths;
+- planning depth, key decisions, and task count;
+- `PLAN_READY` when artifacts pass planning review, otherwise `PLAN_BLOCKED` with unresolved planning blockers.
 
-1. If workflow state names an active `orchestrator`, return `PLAN_READY`, `stage_result=PLAN_READY`, `next_stage=implement`, the state path, and the same `artifact_dir` to that orchestrator; do not invoke the next stage independently.
-2. For direct stage use with no active orchestrator, report exactly one deterministic next action: `/prizmkit-implement`, with `stage_result=PLAN_READY`, the state-file path, and `artifact_dir`; a host may perform that semantic handoff on the user's behalf.
+Return only the listed planning outputs. Do not invoke another Skill.
 
 Read `${SKILL_DIR}/references/examples.md` only when a worked planning example is needed.