prizmkit 1.1.154 → 1.1.155

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

@@ -1,174 +0,0 @@
-# PrizmKit Workflow State Protocol
-
-`workflow-state.json` is lifecycle metadata for one formal requirement. It preserves stage handoff, orchestrator ownership, and resume information without replacing skill-owned artifacts or any host-owned execution checkpoint.
-
-## Location and Identity
-
-```text
-.prizmkit/state/workflows/<requirement-slug>.json
-```
-
-The active `artifact_dir` is preserved exactly across every stage:
-
-```text
-.prizmkit/specs/<requirement-slug>/
-.prizmkit/bugfix/<bug-id>/
-.prizmkit/refactor/<refactor-id>/
-```
-
-Never select another recent plan when resuming. Any external execution checkpoint remains separate from this state. Never merge, substitute, or infer one schema from the other.
-
-## 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 result | `{artifact_dir}/review-report.md` |
-| Test semantics and native execution | `{artifact_dir}/test-report.md` |
-| Terminal testing result | `{artifact_dir}/test-result.json` |
-| Retrospective completion | `{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 | External host checkpoint |
-
-Every consumer compares workflow state with the skill-owned artifacts and 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": "completed",
-  "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. |
-| `artifact_dir` | Generic requirement artifact root reused by every stage. |
-| `orchestrator` | Semantic coordinator identifier, or null for direct stage use. |
-| `stage` | Stage that most recently wrote state. |
-| `status` | Lifecycle status: `pending`, `in_progress`, `completed`, `failed`, or `skipped`. |
-| `stage_result` | Domain result for the current stage, such as `PLAN_READY`, `IMPLEMENTED`, `REVIEW_PASS`, `REVIEW_NEEDS_FIXES`, `TEST_*`, `RETRO_COMPLETE`, or `COMMITTED`. |
-| `completed_stages` | Ordered stages completed for this requirement. |
-| `repair_scope` | Optional caller-owned routing scope. The test skill reports high-risk repairs through `test-result.json` instead of scheduling another stage. |
-| `repair_round` | Optional outer cross-stage repair round, from 0 through 3. It is not a test-internal repair counter. |
-| `next_stage` | Next semantic stage, or null when stopped. |
-| `resume_from` | Exact atomic skill that can resume, or null when none is selected. |
-
-`status` and `stage_result` are deliberately separate. Lifecycle status values must never be replaced with domain result values.
-
-## Lifecycle and Result Mappings
-
-```text
-PLAN_READY
-→ IMPLEMENTED
-→ REVIEW_PASS
-→ TEST_PASS
-→ RETRO_COMPLETE
-→ COMMIT_PENDING
-→ COMMITTED
-```
-
-No formal stage is silently optional. Domain artifacts map to workflow state as follows:
-
-```text
-plan PLAN_READY                  → status=completed,  stage_result=PLAN_READY
-plan PLAN_BLOCKED                → status=failed,     stage_result=PLAN_BLOCKED
-implementation IMPLEMENTED       → status=completed,  stage_result=IMPLEMENTED
-implementation repair/block      → status=failed,     stage_result=IMPLEMENT_REPAIR or IMPLEMENT_BLOCKED
-review-report PASS               → status=completed,  stage_result=REVIEW_PASS
-review-report NEEDS_FIXES        → status=failed,     stage_result=REVIEW_NEEDS_FIXES
-test-result TEST_PASS            → status=completed,  stage_result=TEST_PASS
-test-result TEST_NEEDS_FIXES     → status=failed,     stage_result=TEST_NEEDS_FIXES
-test-result TEST_BLOCKED         → status=failed,     stage_result=TEST_BLOCKED
-retrospective DOCS_UPDATED       → status=completed,  stage_result=RETRO_COMPLETE
-retrospective NO_DOC_CHANGE      → status=completed,  stage_result=RETRO_COMPLETE
-retrospective blocked            → status=failed,     stage_result=RETRO_BLOCKED
-commit authorization pending     → status=in_progress, stage_result=COMMIT_PENDING
-local commit confirmed           → status=completed,  stage_result=COMMITTED
-commit blocked                   → status=failed,     stage_result=COMMIT_BLOCKED
-```
-
-`DOCS_UPDATED` and `NO_DOC_CHANGE` remain retrospective artifact `result` values. The workflow `stage_result` is the retrospective stage result `RETRO_COMPLETE`.
-
-`TEST_PASS` requires both `test-report.md` and a consistent `test-result.json`. No manifest, attestation, evidence package, or test-internal checkpoint is part of this contract.
-
-## Non-Pass Results and Routing Boundary
-
-`prizmkit-test` performs its own bounded failure repair and review loops before returning. The test skill never invokes another lifecycle stage.
-
-```text
-TEST_NEEDS_FIXES
-→ known correction or required delta review remains
-→ caller decides whether and how to arrange another stage
-
-TEST_BLOCKED
-→ truth, input, safe environment, or reliable execution prevents a verdict
-→ never make speculative production edits
-→ caller or external host owns recovery policy
-```
-
-A test result is not an AI CLI session classification. `TEST_NEEDS_FIXES` and `TEST_BLOCKED` must not be rewritten as crash or infrastructure failure merely because they stop lifecycle progression.
-
-Any outer repair or continuation policy is independently owned by the caller and cannot alter the test report. The Main-Agent test review limit of ten rounds, independent Test Reviewer limit of five responses, and execution-failure repair limit of three rounds are internal to one test invocation and do not update outer counters.
-
-## Orchestrator Ownership and Handoff
-
-1. An atomic stage performs only its own stage, writes its truthful result and artifact paths, and returns control.
-2. When `orchestrator` is non-null, only that orchestrator invokes the next skill.
-3. Direct stage use may report a possible next invocation but does not claim it ran.
-4. Every handoff preserves the same `artifact_dir`.
-5. External automation invokes atomic stages directly and does not nest the composite workflow.
-6. Workflow state never replaces or absorbs an external host checkpoint.
-
-## Commit Authorization
-
-Interactive execution:
-
-```text
-committer previews intended files and message
-→ waits for explicit current-user confirmation
-→ creates the local commit
-```
-
-Trusted headless execution:
-
-```text
-trusted host explicitly authorizes the current local task commit
-→ committer verifies gates and commits automatically
-→ remote publication remains separate
-```
-
-A self-declared or untrusted headless context does not authorize a commit.
-
-## Recovery
-
-When state is missing, stale, or inconsistent:
-
-1. Reuse current context, then read `spec.md` and `plan.md` only when needed.
-2. Inspect task markers and current workspace.
-3. Read the current review report when needed to establish review authority.
-4. Validate that `test-report.md` and terminal `test-result.json` exist, agree, and reflect the claimed result.
-5. Validate `retrospective-result.json` when retrospective is claimed complete.
-6. Verify the commit when commit is claimed complete.
-7. Let an active external host validate its own checkpoint independently.
-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 checkpoint enforcement.

package/bundled/skills/prizmkit-test/references/external-contract-mock-guidance.md

@@ -1,119 +0,0 @@
-# External Contract Mock Guidance
-
-## Purpose
-
-Use traceable contracts to model external services, persistence, filesystems, queues, generated clients, browser-facing backends, and cross-module endpoints without connecting tests to production targets or inventing provider behavior.
-
-Mocks are test tools, not proof of a deployed environment.
-
-## Contract Source Order
-
-Use the highest available source:
-
-1. project-owned OpenAPI, JSON Schema, Protocol Buffers, GraphQL, AsyncAPI, database schema, generated types, SDK interfaces, fixtures, and documentation;
-2. vendored or lock-version-matched dependency documentation;
-3. public official service documentation obtained through approved read-only web retrieval;
-4. observed non-production behavior only when explicitly authorized and safely isolated.
-
-Use the current locked/provider version when behavior differs by version. Record the source path, public URL, document/version identifier, or generated type used in `test-report.md`.
-
-Never invent fields, statuses, error shapes, retry rules, pagination behavior, ordering, or timing guarantees without a traceable source.
-
-## Safe Documentation Retrieval
-
-Public official documentation retrieval may be used only to read the minimum contract material needed for tests.
-
-- Do not send source code, repository-private content, proprietary payloads, secrets, credentials, or user data to a public endpoint.
-- Prefer a project-local or vendored source when it is authoritative.
-- Distinguish official provider documentation from blogs, examples, forum answers, and third-party tutorials.
-- When official sources conflict with the project's pinned generated client or schema, apply the skill's truth precedence and report the conflict.
-- If the required contract cannot be established, return `TEST_BLOCKED` when it prevents a safe verdict.
-
-## Build the Smallest Faithful Double
-
-Use the target project's existing fake, fixture, mock library, mock server, container, or isolated service when adequate. Model only behavior relevant to the affected module, but preserve the contract property being tested.
-
-Applicable variants include:
-
-- normal success;
-- empty success;
-- minimum, maximum, pagination, cursor, or size boundary;
-- malformed or contract-invalid response;
-- timeout or cancellation;
-- rate limiting or quota rejection;
-- authentication or authorization rejection;
-- transient service failure;
-- permanent service failure;
-- partial response or interrupted stream;
-- retry, replay, and idempotency behavior;
-- transaction, constraint, rollback, or conflict behavior for stateful services.
-
-Do not require every variant mechanically. Select variants from the actual behavior/risk model and explain material omissions.
-
-## Assertions
-
-Assert the application's observable handling of the contract:
-
-- outbound request shape, required headers or metadata, and serialization;
-- response mapping, nullability, enum and format handling;
-- retry count and retryable versus permanent classification;
-- timeout and cancellation propagation;
-- pagination and cursor behavior;
-- idempotency and side-effect counts;
-- state transition, rollback, cleanup, and absence of partial effects;
-- consumer-visible error type or result.
-
-A mock-success-only test is insufficient when dependency failure can change observable behavior.
-
-## Avoid Over-Mocking
-
-Keep production composition real when that composition is the property under test. Mock at a stable external boundary rather than mocking the method being verified or every internal collaborator.
-
-Reject a double when it:
-
-- repeats the current implementation instead of the external contract;
-- bypasses serialization, mapping, retries, or state transitions under test;
-- returns impossible provider behavior;
-- asserts only that a mock was called without proving the business result;
-- silently drifts from the project or official contract.
-
-Use contract/integration or isolated infrastructure tests when a mock cannot preserve the relevant transaction, protocol, or composition property.
-
-## Databases and Stateful Services
-
-Prefer project-provided isolated infrastructure, a faithful local fake, or a disposable service. Derive structure and constraints from schemas, migrations, models, or official protocol contracts.
-
-Any disposable resource must have:
-
-- a unique non-production identity;
-- bounded lifetime;
-- deterministic setup;
-- verified cleanup;
-- no dependency on production credentials or data.
-
-Test relevant constraints, transactions, rollback, concurrency, idempotency, and failure mapping. Cleanup failure that undermines reliability produces `TEST_BLOCKED`.
-
-## Production and Data Prohibitions
-
-Never use:
-
-- production credentials or tokens;
-- production databases, APIs, queues, object storage, caches, or services;
-- real customer or user data;
-- a target whose non-production status cannot be established;
-- destructive operations against external data.
-
-Project configuration may be reused only when it demonstrably selects a safe isolated test target. If safety cannot be proven, do not connect; report the unexecuted check and return `TEST_BLOCKED` when it is necessary for the verdict.
-
-## Reporting
-
-For every material external contract, record:
-
-- dependency and behavior under test;
-- contract source and version when available;
-- mock/fake/isolated-service strategy;
-- variants exercised;
-- production resources used: `no`;
-- unresolved fidelity or deployed-environment risk.
-
-Do not claim that a local mock, fake, contract snapshot, container, or isolated service verifies a deployed production environment.