# Deterministic Workflow Authority

PRD Plugin executes every bounded lifecycle operation through the managed
workflow engine when a shipped definition exists. Prompt text and skills route
work; they are not execution engines.

## Ownership boundary

The deterministic engine owns input validation, action selection, sequencing,
policy gates, canonical state-tool calls, exact repository facts, verification
plans, checks, checkpoints, receipts, retries, cancellation, output bounds, and
postconditions.

An LLM owns only work that cannot be answered by a finite validated rule:
requirements interpretation, competing-cause diagnosis, architectural tradeoff,
material code-review judgment, and source-backed explanatory synthesis.

Judgment is an explicit `judgment.request` step. The engine pauses in
`waiting_judgment` and emits an immutable request containing its sources,
source hashes where available, result schema, executor/profile, constraints,
and request hash. AI-Collab or another configured runtime may execute it. The
engine validates the returned hash, executor/profile, schema, and provenance
before it resumes. The model never writes canonical state.

## Soundness guarantee

`completed` means every declared postcondition passed. External availability is
not guaranteed: unavailable processes, filesystems, Git, networks, registries,
or models produce explicit `failed`, `blocked`, or `waiting_judgment` outcomes.
They never produce false success.

## State and replay

Runs use duplicate-safe `WFR-*` IDs and live in
`.prd_plugin/state/workflow-runs.json`. Every step records input/output hashes,
timestamps, action identity, and a receipt. Stable idempotency keys return the
existing run for identical inputs and reject reuse with different inputs.

Non-idempotent actions are checkpointed before execution. If interruption makes
their outcome unknowable, the run is blocked with `outcome_unknown`; automatic
replay is forbidden until canonical state is reconciled.

## Configuration

`.prd_plugin/config.json` is the only policy authority. `workflows.enabled`,
`enabled_ids`, `allow_custom_definitions`, `allow_state_mutations`, retry/output
bounds, and the judgment executor/profile/fallback are validated by
`prd_config.py`. Shipped JSON may select only code-owned registered actions and
cannot embed shell or Python.

## Interfaces

- CLI: `.prd_plugin/scripts/prd_workflows.py`
- MCP: `prd_workflow_list/actions/audit/plan/run/status/resume/cancel/retry`
- UTCP: read-only `workflow` list/actions/audit/plan/status projection
- Command: `/prd-workflow`
- Skill: `project-deterministic-workflows`

SessionStart and Stop dispatch through `session.start` and `session.stop` when
their hook switches are enabled. Specialized hook emitters remain responsible
for host protocol output, but the engine owns their lifecycle preflight and
receipts.

## Skill semantic contract

Every shipped workflow ID is named by its owning domain skill as well as
`project-deterministic-workflows`. The hub contract at
`templates/feature-skill-map.json` also covers current commands and cross-cutting
capabilities. `feature_skill_audit.py` reports CHML findings when required
guidance disappears or obsolete guidance returns; `workflow_chml_audit.py` and
`local_workflow_check.py` run it at the release boundary.

## Verification policy

Incremental work uses `engineering.verify` and the conservative impact-scoped
plan. `hub.release` is the one shipped workflow that deliberately performs the
release-wide suite, release/gap checks, package check, and state gate.