prizmkit 1.1.129 → 1.1.131

package/bundled/skills/prizmkit/SKILL.md

@@ -1,139 +1,175 @@
 ---
 name: "prizmkit"
-description: "Full-lifecycle PrizmKit development toolkit index. Routes users to the right core skill for project init, planning, implementation, review, docs maintenance, testing, commit, and deploy. Use when the user asks 'which command?', 'help', 'how do I start a feature', 'get started', 'what tools', 'dev workflow', 'lifecycle', or '/prizmkit'. Clarifies Direct edit vs Fast path vs Full path and asks whether ambiguous 'ship it' means commit or deploy. (project)"
+description: "PrizmKit framework introduction and lifecycle navigator. Explains the independent project-init, formal requirement lifecycle, documentation, and deployment skills. Use when users ask what PrizmKit is, which skill to use, how to start, or how the lifecycle works. (project)"
 ---
 
-# PrizmKit — Full-Lifecycle Development Toolkit
+# PrizmKit — Framework Introduction and Navigator
 
-### When to Use
-- User asks "which command?", "help", "how do I start a feature", "get started", "what tools"
-- User wants to understand the PrizmKit development lifecycle
-- User invokes "/prizmkit" or asks about dev workflow
-- User is new to the project and needs orientation
-- User says an ambiguous phrase such as "ship it" and intent could mean commit or deploy
+`/prizmkit` explains the PrizmKit toolkit and directs the user to the appropriate independent skill. It does not execute a requirement lifecycle itself.
 
-### When NOT to Use
-- User already knows which specific skill to use — invoke that skill directly
-- Mid-implementation — use the specific skill needed (`/prizmkit-implement`, `/prizmkit-code-review`, etc.)
-- User wants to execute immediately without orientation — route to the correct specific skill
+## When to Use
 
-## Task Execution Model
+- User asks what PrizmKit is or which skill to use.
+- User asks how to start a project or a formal requirement.
+- User asks about the development lifecycle or available tools.
+- User invokes `/prizmkit`.
+- User uses an ambiguous phrase such as "ship it" and the intent could mean commit or deploy.
 
-PrizmKit uses self-contained task sessions. Each task starts by reading project context and ends by preserving durable knowledge when the change warrants it.
+## When NOT to Use
 
-Per-task context normally comes from:
+- User already knows the required skill; invoke that skill directly.
+- A formal requirement is already in progress; continue from its workflow state and current stage.
+- User wants an immediate low-risk direct edit; perform the edit and its specific verification.
 
-**Application level**:
-- `.prizmkit/prizm-docs/root.prizm` — L0 project architecture index
-- `.prizmkit/plans/project-brief.md` — product vision generated during project initialization
-- `.prizmkit/config.json` — tech stack and runtime config
+## Responsibility Map
 
-**Task level**:
-- `spec.md` / `plan.md` — change artifact for the current task
-- Relevant `.prizmkit/prizm-docs/<module>.prizm` L1 docs
-- Relevant L2 docs when they exist; if an L2 doc is missing, implementation reads the target source files as fallback and retrospective may create L2 afterward
+```text
+PrizmKit Toolkit
+├── prizmkit
+│   └── Framework introduction and navigation
+├── prizmkit-workflow
+│   └── One-entry orchestration for the formal requirement lifecycle
+├── prizmkit-init
+│   └── Recommended one-time project initialization
+├── Formal requirement lifecycle
+│   ├── prizmkit-plan
+│   ├── prizmkit-implement
+│   ├── prizmkit-code-review
+│   ├── prizmkit-test
+│   ├── prizmkit-retrospective
+│   └── prizmkit-committer
+├── prizmkit-prizm-docs
+│   └── Independent Prizm documentation management
+└── prizmkit-deploy
+    └── Independent deployment and operations entry point
+```
+
+## Formal Requirement Lifecycle
+
+Every formal requirement follows all six stages in this order:
+
+```text
+prizmkit-plan
+  → prizmkit-implement
+  → prizmkit-code-review
+  → prizmkit-test
+  → prizmkit-retrospective
+  → prizmkit-committer
+```
+
+The lifecycle starts at `/prizmkit-plan`. For a one-entry experience, invoke `/prizmkit-workflow` with the requirement; it coordinates the same stages without replacing their responsibilities. When the host supports skill-to-skill handoff, the stages continue automatically. Otherwise, each stage writes the next semantic skill and the workflow state provides the deterministic resume context.
+
+All six stages are required for a formal requirement. A stage may choose a verification depth appropriate to the change, but it may not be silently skipped.
+
+### Direct Edit
+
+Typos, pure formatting, small documentation edits, and other explicitly low-risk non-requirement changes may use a direct edit. Direct edit is not the formal requirement lifecycle.
+
+### Stage Responsibilities
+
+| Stage | Responsibility | Success handoff |
+|---|---|---|
+| `prizmkit-plan` | Clarify the requirement and create/review `spec.md` and `plan.md`. | `PLAN_READY` → `prizmkit-implement` |
+| `prizmkit-implement` | Execute the plan tasks and record completion. | `IMPLEMENTED` → `prizmkit-code-review` |
+| `prizmkit-code-review` | Main Agent reviews, repairs, verifies, and loops until convergence. | `REVIEW_PASS` → `prizmkit-test` |
+| `prizmkit-test` | Validate the final reviewed workspace with project-native evidence. | `TEST_PASS` → `prizmkit-retrospective` |
+| `prizmkit-retrospective` | Synchronize durable project documentation or record no documentation change. | `RETRO_COMPLETE` → `prizmkit-committer` |
+| `prizmkit-committer` | Verify gates, request commit confirmation, and create the local commit. | `COMMITTED` |
 
-## Lifecycle Paths
+### `prizmkit-workflow`
 
-Choose the lightest path that still protects correctness. Explain the chosen path briefly before proceeding.
+Use for a one-entry formal requirement workflow. It coordinates all six lifecycle skills, preserves one `artifact_dir`, routes failures, and stops for commit confirmation. It handles exactly one requirement per invocation.
 
-### Direct edit
+### `prizmkit-init`
 
-Use for low-risk work with no meaningful behavior or interface impact.
+`/prizmkit-init` is recommended the first time PrizmKit enters a project. It can create project context, configuration, a project brief, and Prizm documentation.
 
-Examples:
-- Typo or wording fixes
-- Pure formatting
-- Small documentation edits
-- Tiny config tweaks with no behavior change
+Initialization is a soft prerequisite, not a hard dependency:
 
-Direct edit does not create `spec.md` or `plan.md`. Run only the verification that fits the edit.
+- If project initialization is missing, `/prizmkit-plan` recommends `/prizmkit-init`.
+- The user may continue without initialization.
+- Planning then reads the source tree, README, manifests, and available project rules as fallback context.
+- Later documentation synchronization reports when the Prizm documentation system is not initialized instead of pretending that synchronization completed.
 
-### Fast path
+## Independent Skills
 
-Use for small, well-scoped behavior changes where a full lifecycle would add more process than value.
+### `prizmkit-prizm-docs`
 
-Default flow:
+Use for Prizm documentation initialization, status, validation, migration, repair, and rebuild. It is not an additional stage required for every formal requirement.
+
+### `prizmkit-deploy`
+
+Use independently after development when deployment or operations work is needed. It is not a seventh requirement stage and does not replace the six development gates.
+
+## Failure and Repair Routing
 
 ```text
-simplified /prizmkit-plan -> /prizmkit-implement -> conditional test/retro -> /prizmkit-committer
+REVIEW_NEEDS_FIXES
+  → prizmkit-implement
+  → prizmkit-code-review
+
+TEST_FAIL affecting only tests, fixtures, or test-runner configuration
+  → prizmkit-implement
+  → prizmkit-test
+
+TEST_FAIL affecting production code, runtime configuration, schema,
+dependencies, or public interfaces
+  → prizmkit-implement
+  → prizmkit-code-review
+  → prizmkit-test
+
+TEST_BLOCKED
+  → pause without speculative code changes
+  → resume from prizmkit-test when the environment is available
 ```
 
-Rules:
-- Use a simplified `plan.md` with a Tasks section so implementation can resume safely.
-- Full `/prizmkit-code-review` is optional unless risk or user request requires it.
-- Run `/prizmkit-test` only when the change hits the risk-triggered testing criteria.
-- Run `/prizmkit-retrospective` only when structure, interfaces, dependencies, behavior, or durable project knowledge changed.
+Automatic outer repair is limited to three rounds. The workflow stops with a resumable blocked result when the limit is reached or a gate cannot be safely completed.
+
+## Commit and Deployment Boundary
 
-### Full path
+`prizmkit-committer` must not create a commit until the preceding five formal stages have succeeded. Before creating the local commit, it presents the intended files, diff summary, and Conventional Commit message and waits for user confirmation.
 
-Use for high-risk work, multi-module changes, new capabilities, architecture changes, public API/interface changes, data model/schema changes, security/permission/payment logic, or unclear requirements.
+Pushing to a remote is a separate explicit action. Deployment is always a separate invocation of `/prizmkit-deploy`.
 
-Default flow:
+## Workflow State
+
+An active requirement may use:
 
 ```text
-/prizmkit-plan -> /prizmkit-implement -> risk-triggered /prizmkit-test if needed -> /prizmkit-code-review -> /prizmkit-retrospective -> /prizmkit-committer
+.prizmkit/state/workflows/<requirement-slug>.json
 ```
 
-Rules:
-- `/prizmkit-plan` produces a full `spec.md` and `plan.md`.
-- `/prizmkit-code-review` is the default quality gate.
-- `/prizmkit-retrospective` is the normal development writer for `.prizmkit/prizm-docs/`.
-- `/prizmkit-test` is risk-triggered rather than always mandatory.
+This runtime state records the current stage, terminal status, repair scope, repair round, and resume entry. The skill set does not prescribe whether the target project commits, ignores, or shares this file.
 
-## Risk-Triggered Testing
+Read `${SKILL_DIR}/references/workflow-state-protocol.md` for the state protocol. If the state file is missing or stale, use `spec.md`, `plan.md`, review evidence, and test evidence to reconstruct the safest recoverable stage and report that reconstruction.
 
-Recommend or require `/prizmkit-test` when the change affects:
-- Observable behavior
-- Public interfaces or API contracts
-- Data models, migrations, or schema
-- Security, permissions, authentication, billing, payments, or entitlements
-- Deployment readiness or user-requested quality verification
+## Quick Start
 
-Skip `/prizmkit-test` for pure docs, formatting, internal renames with no behavior change, or tiny config tweaks unless the user asks for tests.
+Install the skills through the host's skills installer, for example:
 
-## Development Scenarios
+```bash
+npx skills add <repository>
+```
 
-PrizmKit supports any development scenario through the same skill chain. `/prizmkit-plan` produces a change artifact (`spec.md` + `plan.md`) regardless of whether the task is a feature, bug fix, refactor, or migration.
+Then:
 
-| Scenario | Artifacts | When to Use |
-|----------|-----------|-------------|
-| Feature | `spec.md` -> `plan.md` -> code | New functionality, UI, API, data model changes |
-| Bug fix | `spec.md` -> `plan.md` -> code | Complex defects, regressions, crash fixes; simple bugs can use Direct edit or Fast path |
-| Refactor | `spec.md` -> `plan.md` -> code | Restructure, extract, rename, performance work with behavior preservation |
+```text
+1. Optionally run /prizmkit-init when entering a project for the first time.
+2. Start a formal requirement with /prizmkit-plan.
+3. Continue through implement → code-review → test → retrospective → committer.
+4. Confirm the local commit when /prizmkit-committer presents it.
+5. Invoke /prizmkit-deploy separately when deployment or operations work is needed.
+```
 
-## Core Skill Reference
+## Scope Boundary
 
-| Skill | Purpose | Trigger Phrases |
-|-------|---------|-----------------|
-| `/prizmkit-init` | Project bootstrap entry point: use before planning in a newly installed/taken-over project; scans codebase, generates `.prizmkit/prizm-docs/`, config, and project brief. | "init", "initialize", "take over this project", "bootstrap" |
-| `/prizmkit-plan` | First implementation planning step: run ahead of `/prizmkit-implement` to turn natural language into `spec.md` + `plan.md` with executable tasks. | "specify", "plan", "new task", "architect", "break it down" |
-| `/prizmkit-implement` | Implementation step: use after `/prizmkit-plan` to execute `plan.md` tasks with TDD where applicable, task order, and checkpoints. | "implement", "build", "code it", "start coding" |
-| `/prizmkit-test` | Risk-triggered quality gate: run after implementation when behavior, interfaces, data, security, or deploy risk requires tests and boundary coverage. | "test", "run tests", "verify", "quality check", "boundary tests" |
-| `/prizmkit-code-review` | Full path quality gate: the current Main Agent reviews and repairs the complete change in the active checkout without direct or indirect review delegation. | "review", "check code", "code review", "is it ready to commit" |
-| `/prizmkit-retrospective` | Docs maintenance step: run after review/implementation when structure, interfaces, dependencies, behavior, or durable knowledge changed. | "retrospective", "retro", "update docs", "sync docs", "wrap up" |
-| `/prizmkit-committer` | Final lifecycle commit step: use after required gates are satisfied; safely stages and creates a Conventional Commit without changing changelog by default. | "commit", "submit", "finish", "done" |
-| `/prizmkit-prizm-docs` | Documentation system entry point: use for init/status/rebuild/validate/migrate or out-of-band repair, not normal development sync. | "initialize docs", "check docs", "rebuild docs", "validate docs", "docs drifted" |
-| `/prizmkit-deploy` | Deployment lifecycle entry point: use after code is ready to release or for existing deployment operations. | "deploy", "go live", "take live", "release", "rollback", "deploy status" |
+This toolkit is self-contained: its skills describe only this toolkit's lifecycle and independent entry points. External systems may integrate through the published skill inputs, outputs, state, and authorization contracts, but their internal architecture and names are outside this toolkit's protocol.
 
-## Ambiguous Ship Intent
+The toolkit does not promise universal automatic handoff, universal deployment automation, automatic remote push, or access beyond the host platform's permissions and environment.
 
 If the user says only "ship it", ask whether they mean:
 
 1. Commit the current changes with `/prizmkit-committer`.
-2. Deploy or release the project with `/prizmkit-deploy`.
-
-Do not route ambiguous "ship it" directly to commit or deploy without clarification.
-
-## Quick Start
-
-1. `npx prizmkit install .` — install skills, rules, hooks, and platform scaffolding
-2. `/prizmkit-init` — scan project, generate docs/config/brief
-3. `/prizmkit-plan` — create a change artifact for the first non-trivial task
-4. `/prizmkit-implement` — implement plan tasks
-5. Run `/prizmkit-test` if risk-triggered
-6. Run `/prizmkit-code-review` for Full path or when requested/risk-triggered
-7. Run `/prizmkit-retrospective` if docs or durable knowledge changed
-8. `/prizmkit-committer` — safe Conventional Commit
+2. Deploy or operate the project with `/prizmkit-deploy`.
 
-> Rules and hooks are installed by `npx prizmkit install`, not by `/prizmkit-init`.
+Do not route an ambiguous "ship it" directly to either action.

package/bundled/skills/prizmkit/references/workflow-state-protocol.md

@@ -0,0 +1,181 @@
+# PrizmKit Workflow State Protocol
+
+`workflow-state.json` is lifecycle runtime metadata for one formal requirement. It preserves stage handoff, repair routing, orchestrator ownership, and resume information without replacing authoritative artifacts or any host-owned execution checkpoint.
+
+## Location and Identity
+
+```text
+.prizmkit/state/workflows/<requirement-slug>.json
+```
+
+The state file is created only when a lifecycle runs. The active `artifact_dir` is the generic requirement artifact root and must be preserved exactly across every stage:
+
+```text
+.prizmkit/specs/<requirement-slug>/
+.prizmkit/bugfix/<bug-id>/
+.prizmkit/refactor/<refactor-id>/
+```
+
+Never select a different most-recent plan when resuming or handing off. Any execution checkpoint maintained by an external host remains separate from this lifecycle state. Never merge, substitute, or infer one schema from the other. The target project controls whether generated `.prizmkit/` files are committed, ignored, or shared.
+
+## Authority
+
+The state file is an index, not the authority for stage completion:
+
+| Information | Authority |
+|---|---|
+| Requirement goals and acceptance criteria | `{artifact_dir}/spec.md` |
+| Implementation tasks and completion | `{artifact_dir}/plan.md` plus current workspace |
+| Review findings and verdict | `{artifact_dir}/review-report.md` final result |
+| Test execution, verdict, and repair scope | Validated evidence package and authoritative `verdict.json` |
+| Test report presentation | `{artifact_dir}/test-report.md` as a derived view only |
+| Retrospective completion and result | `{artifact_dir}/retrospective-result.json` |
+| Durable architecture knowledge | `.prizmkit/prizm-docs/` |
+| Local commit | Git history and confirmed or authorized commit identity |
+| Current stage, orchestrator, and resume entry | Workflow state |
+| External orchestration progress | The external host's own checkpoint, never this state |
+
+Every consumer compares workflow state with authoritative artifacts and the current workspace. Missing or stale state is reconstructed from those sources and is never accepted as success by itself.
+
+## Schema
+
+```json
+{
+  "schema_version": 1,
+  "artifact_dir": ".prizmkit/specs/example",
+  "orchestrator": "prizmkit-workflow",
+  "stage": "test",
+  "status": "TEST_PASS",
+  "stage_result": "TEST_PASS",
+  "completed_stages": ["plan", "implement", "code-review", "test"],
+  "repair_scope": null,
+  "repair_round": 0,
+  "next_stage": "retrospective",
+  "resume_from": "prizmkit-retrospective"
+}
+```
+
+### Fields
+
+| Field | Meaning |
+|---|---|
+| `schema_version` | State schema version. Current value is `1`. |
+| `artifact_dir` | The single generic requirement artifact root reused by every stage. |
+| `orchestrator` | `prizmkit-workflow`, another semantic coordinator identifier, or `null` for direct stage use. |
+| `stage` | The stage that most recently wrote state. |
+| `status` | Lifecycle progression status, distinct from the domain `stage_result`. |
+| `stage_result` | Domain result such as `PASS`, `NEEDS_FIXES`, `TEST_*`, `DOCS_UPDATED`, or `NO_DOC_CHANGE`. |
+| `completed_stages` | Ordered stages completed for this requirement. |
+| `repair_scope` | `null`, `test-infrastructure`, `production`, `runtime`, `schema`, `dependency`, `public-interface`, or `unknown`. |
+| `repair_round` | Outer cross-stage repair round, from `0` through `3`. |
+| `next_stage` | Next semantic stage, or `null` after commit. |
+| `resume_from` | Exact atomic skill that can resume, or `null` after commit. |
+
+## Lifecycle and Verdict Mappings
+
+The mandatory formal lifecycle is:
+
+```text
+PLAN_READY
+  → IMPLEMENTED
+  → REVIEW_PASS
+  → TEST_PASS
+  → RETRO_COMPLETE
+  → COMMIT_PENDING
+  → COMMITTED
+```
+
+No formal stage is silently optional. Domain evidence maps as follows:
+
+```text
+review-report final PASS        → status=REVIEW_PASS, stage_result=PASS
+review-report final NEEDS_FIXES → status=REVIEW_NEEDS_FIXES, stage_result=NEEDS_FIXES
+validated verdict TEST_PASS     → status=TEST_PASS, stage_result=TEST_PASS
+validated verdict TEST_FAIL     → status=TEST_FAIL, stage_result=TEST_FAIL
+validated verdict TEST_BLOCKED  → status=TEST_BLOCKED, stage_result=TEST_BLOCKED
+retrospective result DOCS_UPDATED  → status=RETRO_COMPLETE, stage_result=DOCS_UPDATED
+retrospective result NO_DOC_CHANGE → status=RETRO_COMPLETE, stage_result=NO_DOC_CHANGE
+```
+
+`RETRO_COMPLETE` is the stable completion status. `DOCS_UPDATED` and `NO_DOC_CHANGE` are mutually exclusive retrospective results, not substitute statuses. A derived Markdown test report never establishes a `TEST_*` status without validated authoritative evidence.
+
+## Repair Routing
+
+```text
+REVIEW_NEEDS_FIXES
+  → implement
+  → code-review
+  → test
+
+TEST_FAIL with repair_scope=test-infrastructure
+  → implement
+  → test
+
+TEST_FAIL with repair_scope=production|runtime|schema|dependency|public-interface
+  → implement
+  → code-review
+  → test
+
+TEST_FAIL with repair_scope=unknown
+  → conservative production route only when safe
+  → otherwise WORKFLOW_BLOCKED
+
+TEST_BLOCKED
+  → never make speculative production edits
+  → interactive execution stops with a prizmkit-test resume entry
+  → a trusted headless host may perform bounded environment recovery, then records WORKFLOW_BLOCKED if unresolved
+
+RETRO_BLOCKED
+  → WORKFLOW_BLOCKED
+WORKFLOW_BLOCKED
+  → resume only after the recorded blocker is resolved
+```
+
+The outer workflow permits at most three automatic repair rounds. These are cross-stage rounds (`repair_round` `0` through `3`). The code-review internal loop permits at most ten completed review rounds and is separate; review-internal repairs do not increment the outer counter.
+
+## Orchestrator Ownership and Handoff
+
+1. An atomic stage performs only its own stage, writes the truthful terminal result and `next_stage`, and returns control.
+2. When `orchestrator` is non-null, only that orchestrator invokes the next skill. The atomic stage must not auto-invoke it again.
+3. Direct stage use may report one deterministic next invocation but does not claim the next stage ran.
+4. Every handoff preserves the same `artifact_dir`.
+5. External automation invokes atomic stages directly and does not invoke `prizmkit-workflow` as a nested coordinator.
+6. Workflow state never replaces or absorbs an external host's checkpoint.
+
+## Commit Authorization
+
+Interactive execution:
+
+```text
+committer previews intended files and message
+→ waits for explicit confirmation from the current user
+→ creates the local commit
+```
+
+Trusted headless execution:
+
+```text
+a trusted host explicitly authorizes the current local task commit
+→ host injects mode=<host-defined-headless-mode>, owner=<trusted-host-identifier>,
+  local_commit_authorized=true, push_authorized=false
+→ committer verifies gates and commits automatically
+→ no question, wait, or push is permitted
+```
+
+A self-declared or otherwise untrusted headless context does not authorize a commit. Push is never implied by either mode.
+
+## Recovery
+
+When state is missing, stale, or inconsistent:
+
+1. Read `spec.md` and `plan.md` from `artifact_dir` only when they are not already available in current context.
+2. Inspect task markers and the current workspace.
+3. Read the latest review report and final result when needed to establish review authority.
+4. Validate authoritative test evidence and `repair_scope`.
+5. Validate `retrospective-result.json` when retrospective is claimed complete.
+6. Verify the commit when commit is claimed complete.
+7. When an external host is active, let that host validate its own checkpoint independently; never merge the schemas.
+8. Reconstruct the latest safe predecessor and report the reconstruction.
+9. Continue only from the first incomplete or invalid stage.
+
+Stale state never bypasses review, testing, retrospective, commit authorization, or external host checkpoint enforcement.