showdar-skills 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -4,7 +4,67 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.7.0]
+
+### Added
+
+- Deterministic workflow trace projection (`src/workflow-trace.js`): pure
+  state-diff observation over workflow transitions with 10 closed semantic
+  event types, no timestamps, no authority content, and no automatic
+  persistence.
+- Workflow benchmark scenario schema and loader
+  (`benchmark/schema/workflow-scenario.schema.json`,
+  `benchmark/lib/workflow-scenario-loader.js`).
+- Deterministic workflow benchmark corpus
+  (`benchmark/scenarios/workflows/`, 16 scenarios): exact-match M1–M10
+  invariants covering selection, skip policy, verification preservation,
+  stale-resume blocking, authority invariance, and completion.
+- `npm run eval:workflows` driver
+  (`scripts/workflow-observability-eval.mjs`).
+
+### Changed
+
+- `npm run eval` now runs retrieval evaluation (`eval:retrieval`) followed
+  by workflow evaluation (`eval:workflows`); release evaluation blocks on
+  exact workflow invariants.
+- `npm run check` remains test/validate/package correctness only.
+
+### Safety
+
+- Traces contain normalized semantic data only (IDs, enums, receipt
+  summaries, statuses): no authority state, raw prompts, logs, telemetry,
+  or network reporting.
+
+## [0.6.0]
+
+### Added
+
+- Portable workflow execution state (`src/workflow-state.js`): versioned
+  JSON checkpoint schema (schemaVersion 1) with stage selection, evidence
+  receipts, structured skip, interruption, and resume. State never persists
+  authority; resume always re-resolves through Phase 6G. Caller/harness
+  owns persistence; no filesystem store, backend, or telemetry.
+- Workflow checkpoint documentation in all four workflow skills
+  (feature, bugfix, release, incident): serialization,
+  interruption/resume, stale-checkpoint blocking, and stage vs workflow
+  completion semantics.
+- Workflow-state policy validation in `src/validate.js`: catalog coverage,
+  no authority fields in checkpoints, no harness or storage coupling.
+
+### Changed
+
+- Four workflow skills now describe adaptive state semantics instead of
+  ephemeral-only tracking.
+- Workflow completion explicitly distinguishes stage completion (primitive
+  evidence and stop conditions) from workflow completion (all selected
+  stages completed or validly skipped, no blockers, required verification
+  satisfied).
+
+### Safety
+
+- Checkpoint state never persists authority-derived fields.
+- Caller owns checkpoint persistence; Showdar chooses no storage.
+- Stale checkpoints block with `replanRequired` rather than continuing.
 
 ## [0.5.0]
 

package/MIGRATION.md

@@ -1,3 +1,42 @@
+# Migrating to 0.7.0
+
+0.7.0 adds deterministic workflow trace projection
+(`src/workflow-trace.js`) and a workflow benchmark corpus over the
+unchanged 0.6 runtime. No user action is required.
+
+- Existing 0.6 installs and configs remain valid: no workflow-state
+  schema migration (still schemaVersion 1), no config migration, no
+  adapter migration, no checkpoint migration.
+- Runtime workflow semantics are unchanged; traces observe released
+  behavior only and never affect execution, routing, or authority.
+- The new `src/workflow-trace.js` module ships in the package; benchmark
+  scenarios, schema, loader, and eval driver are development/release
+  tooling and do not ship.
+- No telemetry, network reporting, automatic storage, or tracking is
+  introduced.
+
+# Migrating to 0.6.0
+
+0.6.0 adds portable workflow execution state (`src/workflow-state.js`,
+schemaVersion 1) over the unchanged 15 primitives, 4 workflows, and Phase 6G
+authority.
+
+- Existing 0.5 installs and configs remain valid; no adapter or config
+  migration is required.
+- The four workflows now support explicit portable execution state:
+  stage selection and progression, evidence-backed skipping, stage vs
+  workflow completion, interruption, and resume.
+- Checkpoints are plain JSON at schemaVersion 1. Persistence is owned by
+  the caller or harness; Showdar 0.6 defines no state directory, backend,
+  session registry, or telemetry.
+- Resume always re-resolves current context through Phase 6G. Stale
+  checkpoints return `BLOCKED` with `replanRequired` instead of silently
+  continuing.
+- Checkpoints never persist authority. No migration of prior route or
+  authority state exists or is needed.
+- No config change is required. Callers that never persist a checkpoint
+  keep the previous ephemeral-only behavior.
+
 # Migrating to 0.5.0
 
 0.5.0 adds a thin native adapter layer over the unchanged portable core.

package/README.md

@@ -385,6 +385,97 @@ primitive (`showdar-review`, `showdar-debug`, `showdar-test`). Phase 6G remains
 the authority source; workflows consume it and never mint it. Workflows are
 opt-in through `showdar add <workflow>`; profiles install primitive sets only.
 
+## Workflow execution state (0.6.0)
+
+```text
+portable workflow
+  -> workflow-state
+  -> primitive evidence/stop conditions
+  -> current Phase 6G resolution
+  -> next stage / blocked / complete
+```
+
+Workflow state (`src/workflow-state.js`, schemaVersion 1) is a portable,
+versioned JSON checkpoint: `workflowId`, selected stages, active stage,
+completed stages, skipped stages, evidence receipts, blockers, next stage,
+`status` (`NEW`/`READY`/`ACTIVE`/`COMPLETE`/`INTERRUPTED`/`BLOCKED`), and a
+deterministic monotonic `revision` counter. Timestamps
+(`createdAt`/`updatedAt`/receipt timestamps) are metadata and provenance only.
+
+Workflow state is NOT authority, memory, router intent, or a persistence
+backend. It never persists authority-derived fields
+(`primaryCapability`, `authorizedAction`, `mutationPermission`,
+`routeAuthority` or equivalents). Checkpoint JSON may be stored by a
+caller or harness anywhere; Showdar 0.6 does not choose or manage storage.
+
+Evidence receipts are compact copies of primitive evidence at stage
+completion (`kind`, `quality`, `source`, `detail`, timestamp, optional
+provenance). Quality follows `claimed < observed < verified`; `failed` and
+`missing` remain meaningful negative states. High-sensitivity evidence
+(change, tests, build, package, compatibility, regression proof, release
+readiness) may require re-verification after resume; old evidence is not
+permanently valid.
+
+Safe resume is always:
+
+```text
+checkpoint
+  -> deserialize + validate
+  -> resolve current request/context through Phase 6G
+  -> compatibility/freshness checks
+  -> READY or BLOCKED + replanRequired
+```
+
+A checkpoint alone can never authorize continuation. Previously authorized
+mutation is never restored from a checkpoint. When the current Phase 6G
+resolution no longer matches the checkpoint, resume returns `BLOCKED` with
+`replanRequired` instead of silently continuing.
+
+Per-workflow skip policy (evidence-backed, never severity or wording alone):
+
+- Feature: requirements/plan/design may be skipped only with policy-backed
+  evidence; build, test, and review always run.
+- Bugfix: debug may be skipped only with verified root-cause evidence;
+  symptom description alone is insufficient; investigation-only requests stop
+  without mutation.
+- Release: readiness does not imply deployment; ops loads only with explicit
+  target plus execution authorization.
+- Incident: severity never grants production mutation; recovery and
+  verification remain gated by current authority.
+
+### Workflow traces (observability, benchmark-only)
+
+Workflow traces are pure projections of before/after workflow states
+(`src/workflow-trace.js`): ordered events such as `stage-entered`,
+`stage-completed`, `stage-skipped`, `workflow-blocked`, `workflow-resumed`,
+and `workflow-completed`. Traces carry stage IDs, skip reasons, receipt
+summaries, and statuses only — no timestamps, no prompts, no secrets, no
+authority content. Nothing persists them automatically; the benchmark
+corpus (`npm run eval:workflows`) uses them to verify selection, skip,
+resume, and completion behavior deterministically.
+
+A workflow trace does not mutate workflow state, affect routing or
+authority, persist automatically, or send telemetry. The 10 event
+categories are `workflow-created`, `stages-selected`, `stage-entered`,
+`evidence-recorded`, `stage-completed`, `stage-skipped`,
+`workflow-blocked`, `workflow-interrupted`, `workflow-resumed`, and
+`workflow-completed`.
+
+### Evaluation
+
+```bash
+npm run eval:retrieval  # retrieval evaluation (unchanged behavior)
+npm run eval:workflows  # deterministic workflow semantic benchmark
+npm run eval            # both, sequentially (release-blocking)
+```
+
+Workflow evaluation asserts exact M1–M10 invariants (selection accuracy,
+invalid-skip rejection, verification preservation, stale-resume blocking,
+authority invariance, completion, trace equality, revision monotonicity,
+checkpoint round-trip, skip-evidence backing) with no fuzzy score
+thresholds. `npm run check` (test/validate/pack) does not run the
+benchmark; the release pipeline runs `npm run eval`, gating both suites.
+
 ## A typical software workflow
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },
@@ -8,7 +8,9 @@
     "test": "node --test",
     "validate": "node bin/showdar.js validate",
     "sync:runtime": "node scripts/sync-runtime.mjs",
-    "eval": "node scripts/retrieval-eval.mjs",
+    "eval": "npm run eval:retrieval && npm run eval:workflows",
+    "eval:retrieval": "node scripts/retrieval-eval.mjs",
+    "eval:workflows": "node scripts/workflow-observability-eval.mjs",
     "check": "npm test && npm run validate && npm pack --dry-run",
     "smoke": "node scripts/package-smoke.mjs",
     "release:check": "node scripts/check-release-version.mjs"

package/skills/showdar-bugfix/SKILL.md

@@ -53,8 +53,12 @@ description: Use when resolving an observed defect end-to-end, adaptively sequen
 
 - Load one primitive at a time; hand off only when its stop condition is met.
 - Each primitive's own SKILL.md governs its stage; do not copy primitive instructions here.
-- Track ephemeral state only: candidate stages, selected stages, active stage, completed evidence, next stage or complete.
-- No persistent checkpoint or resume infrastructure in this version.
+- Track portable workflow state (`src/workflow-state.js`): candidate stages, selected stages, active stage, completed evidence receipts, skipped stages with structured reason plus evidence plus policy, next stage or complete, status, revision.
+- Checkpoint by serializing state to plain JSON; caller or harness owns persistence. No filesystem or backend store is implied.
+- Interrupt explicitly to preserve completed plus skipped plus evidence state without inventing completion.
+- Resume by validating the checkpoint, re-resolving current context through Phase 6G, checking workflow compatibility, then continuing or blocking with replan-required.
+- Stored state never authorizes continuation; debug may be skipped only with proven root-cause evidence under policy, never from symptom description alone.
+- Stage completion comes from primitive evidence and stop conditions; workflow completion requires root cause proven plus fix implemented plus verification plus review.
 
 ## Decision points
 

package/skills/showdar-feature/SKILL.md

@@ -56,8 +56,12 @@ description: Use when implementing a complete feature end-to-end, adaptively seq
 
 - Load one primitive at a time; hand off only when its stop condition is met.
 - Each primitive's own SKILL.md governs its stage; do not copy primitive instructions here.
-- Track ephemeral state only: candidate stages, selected stages, active stage, completed evidence, next stage or complete.
-- No persistent checkpoint or resume infrastructure in this version.
+- Track portable workflow state (`src/workflow-state.js`): candidate stages, selected stages, active stage, completed evidence receipts, skipped stages with structured reason plus evidence plus policy, next stage or complete, status, revision.
+- Checkpoint by serializing state to plain JSON; caller or harness owns persistence. No filesystem or backend store is implied.
+- Interrupt explicitly to preserve completed plus skipped plus evidence state without inventing completion.
+- Resume by validating the checkpoint, re-resolving current context through Phase 6G, checking workflow compatibility, then continuing or blocking with replan-required.
+- Stored state never authorizes continuation; skip requires policy plus evidence, never severity or wording alone.
+- Stage completion comes from primitive evidence and stop conditions; workflow completion requires every selected stage completed or validly skipped, no blockers, and required verification satisfied.
 
 ## Decision points
 

package/skills/showdar-incident/SKILL.md

@@ -57,8 +57,12 @@ description: Use when investigating and recovering from an active operational in
 
 - Load one primitive at a time; hand off only when its stop condition is met.
 - Each primitive's own SKILL.md governs its stage; do not copy primitive instructions here.
-- Track ephemeral state only: candidate stages, selected stages, active stage, completed evidence, next stage or complete.
-- No persistent checkpoint or resume infrastructure in this version.
+- Track portable workflow state (`src/workflow-state.js`): candidate stages, selected stages, active stage, completed evidence receipts, skipped stages with structured reason plus evidence plus policy, next stage or complete, status, revision.
+- Checkpoint by serializing state to plain JSON; caller or harness owns persistence. No filesystem or backend store is implied.
+- Interrupt explicitly to preserve completed plus skipped plus evidence state without inventing completion.
+- Resume by validating the checkpoint, re-resolving current context through Phase 6G, checking workflow compatibility, then continuing or blocking with replan-required.
+- Stored state never authorizes continuation; severity never grants production mutation, and ops loads only with explicit environment plus action authority.
+- Stage completion comes from primitive evidence and stop conditions; workflow completion requires recovery plus verification per policy, not merely diagnosis.
 
 ## Decision points
 

package/skills/showdar-release/SKILL.md

@@ -54,8 +54,12 @@ description: Use when preparing, validating, or executing a release lifecycle, a
 
 - Load one primitive at a time; hand off only when its stop condition is met.
 - Each primitive's own SKILL.md governs its stage; do not copy primitive instructions here.
-- Track ephemeral state only: candidate stages, selected stages, active stage, completed evidence, next stage or complete.
-- No persistent checkpoint or resume infrastructure in this version.
+- Track portable workflow state (`src/workflow-state.js`): candidate stages, selected stages, active stage, completed evidence receipts, skipped stages with structured reason plus evidence plus policy, next stage or complete, status, revision.
+- Checkpoint by serializing state to plain JSON; caller or harness owns persistence. No filesystem or backend store is implied.
+- Interrupt explicitly to preserve completed plus skipped plus evidence state without inventing completion.
+- Resume by validating the checkpoint, re-resolving current context through Phase 6G, checking workflow compatibility, then continuing or blocking with replan-required.
+- Stored state never authorizes continuation; ops is skipped under readiness-only policy and never implied by release completion.
+- Stage completion comes from primitive evidence and stop conditions; workflow completion means readiness verification per policy, not implicit deployment.
 
 ## Decision points
 

package/src/validate.js

@@ -221,6 +221,112 @@ async function validateCsvFiles(skillDir, errors) {
   }
 }
 
+export async function validateWorkflowStatePolicy(packageRoot) {
+  const errors = [];
+  const primitives = new Set(SKILLS.map((skill) => skill.id));
+  let policy;
+  try {
+    policy = await import('./workflow-state.js');
+  } catch (error) {
+    return { ok: false, errors: [`workflow-state policy unavailable: ${error.message}`] };
+  }
+  for (const workflow of WORKFLOW_SKILLS) {
+    const stages = policy.selectableStages(workflow.id);
+    if (!Array.isArray(stages) || !stages.length) {
+      errors.push(`workflow-state: ${workflow.id} has no state policy coverage`);
+      continue;
+    }
+    for (const stage of stages) {
+      if (!primitives.has(stage)) errors.push(`workflow-state: ${workflow.id} policy references unknown stage ${stage}`);
+    }
+    const catalogStages = new Set(workflow.stages);
+    for (const stage of stages) {
+      if (!catalogStages.has(stage)) errors.push(`workflow-state: ${workflow.id} policy stage ${stage} not in catalog`);
+    }
+    for (const stage of workflow.stages) {
+      if (!stages.includes(stage)) errors.push(`workflow-state: ${workflow.id} policy missing catalog stage ${stage}`);
+    }
+  }
+  const moduleText = await readFile(path.join(packageRoot, 'src', 'workflow-state.js'), 'utf8').catch(() => '');
+  const forbiddenPersisted = ['primaryCapability', 'authorizedAction', 'mutationPermission', 'routeAuthority'];
+  for (const forbidden of forbiddenPersisted) {
+    const pattern = new RegExp(`['"]${forbidden}['"]\\s*:|\\b${forbidden}\\b\\s*[:=]`, 'g');
+    const matches = moduleText.match(pattern) ?? [];
+    const rejectionList = (moduleText.match(/FORBIDDEN_AUTHORITY_KEYS[\s\S]{0,400}/) ?? [''])[0];
+    const outsideRejection = matches.filter((m) => !rejectionList.includes(forbidden.toLowerCase()));
+    if (outsideRejection.length) {
+      errors.push(`workflow-state: checkpoint schema must not persist ${forbidden}`);
+    }
+  }
+  for (const harness of ['adapters.js', 'adapter-renderers', '.opencode', '.claude', '.cursor']) {
+    if (moduleText.includes(`from './${harness}`) || moduleText.includes(`from "./${harness}`) || moduleText.includes(`import '${harness}`)) {
+      errors.push(`workflow-state: must not import harness module ${harness}`);
+    }
+  }
+  for (const storage of ['.showdar/state', '~/.showdar', 'sqlite', 'telemetry']) {
+    if (moduleText.toLowerCase().includes(storage.toLowerCase())) errors.push(`workflow-state: no storage layer reference ${storage}`);
+  }
+  for (const error of (await validateWorkflowScenarioCoverage(packageRoot, policy)).errors) errors.push(error);
+  return { ok: errors.length === 0, errors };
+}
+
+export async function validateWorkflowScenarioCoverage(packageRoot, policy = null) {
+  const errors = [];
+  const primitives = new Set(SKILLS.map((skill) => skill.id));
+  const workflows = new Set(WORKFLOW_SKILLS.map((w) => w.id));
+  let trace;
+  try {
+    trace = await import('./workflow-trace.js');
+  } catch (error) {
+    return { ok: false, errors: [`workflow-trace unavailable: ${error.message}`] };
+  }
+  const eventTypes = new Set(trace.WORKFLOW_EVENT_TYPES);
+  let files;
+  try {
+    files = await readdir(path.join(packageRoot, 'benchmark', 'scenarios', 'workflows'));
+  } catch {
+    return { ok: false, errors: ['workflow-scenarios: benchmark/scenarios/workflows missing'] };
+  }
+  const scenarioFiles = files.filter((f) => f.endsWith('.json')).sort();
+  if (!scenarioFiles.length) return { ok: false, errors: ['workflow-scenarios: no scenario files'] };
+  const seenIds = new Set();
+  const coverage = new Map();
+  for (const file of scenarioFiles) {
+    let scenario;
+    try {
+      scenario = JSON.parse(await readFile(path.join(packageRoot, 'benchmark', 'scenarios', 'workflows', file), 'utf8'));
+    } catch (error) {
+      errors.push(`workflow-scenarios: ${file} is not valid JSON (${error.message})`);
+      continue;
+    }
+    if (seenIds.has(scenario.id)) errors.push(`workflow-scenarios: duplicate id ${scenario.id}`);
+    seenIds.add(scenario.id);
+    if (!workflows.has(scenario.workflow)) {
+      errors.push(`workflow-scenarios: ${file} references unknown workflow ${scenario.workflow}`);
+      continue;
+    }
+    coverage.set(scenario.workflow, (coverage.get(scenario.workflow) ?? 0) + 1);
+    const catalogStages = new Set((policy?.selectableStages?.(scenario.workflow)) ?? []);
+    for (const stage of scenario.selection?.selectedStages ?? []) {
+      if (!primitives.has(stage)) errors.push(`workflow-scenarios: ${file} selects unknown stage ${stage}`);
+      else if (catalogStages.size && !catalogStages.has(stage)) errors.push(`workflow-scenarios: ${file} selects non-catalog stage ${stage}`);
+    }
+    for (const step of scenario.steps ?? []) {
+      if (step.stage && !primitives.has(step.stage)) errors.push(`workflow-scenarios: ${file} step references unknown stage ${step.stage}`);
+    }
+    for (const entry of scenario.expected?.trace ?? []) {
+      if (!eventTypes.has(entry.type)) errors.push(`workflow-scenarios: ${file} expects unknown event type ${entry.type}`);
+      if (entry.stage !== null && entry.stage !== undefined && !primitives.has(entry.stage)) {
+        errors.push(`workflow-scenarios: ${file} expects unknown event stage ${entry.stage}`);
+      }
+    }
+  }
+  for (const workflow of WORKFLOW_SKILLS) {
+    if (!coverage.get(workflow.id)) errors.push(`workflow-scenarios: ${workflow.id} has no scenario coverage`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
 export async function validateRepository(packageRoot) {
   const errors = [];
   const warnings = [];
@@ -254,6 +360,8 @@ export async function validateRepository(packageRoot) {
     if (new Set(workflow.stages).size !== workflow.stages.length) errors.push(`${workflow.id}: candidate stages contain duplicates`);
   }
 
+  for (const error of (await validateWorkflowStatePolicy(packageRoot)).errors) errors.push(error);
+
   let canonicalRuntime;
   try {
     canonicalRuntime = await readFile(path.join(packageRoot, CANONICAL_RUNTIME_FILE));

package/src/workflow-state.js

@@ -0,0 +1,628 @@
+import { WORKFLOW_SKILLS, getWorkflow, SKILLS } from './catalog.js';
+import { EVIDENCE_KINDS, EVIDENCE_QUALITIES, getStopConditions } from './evidence-state.js';
+
+export const WORKFLOW_SCHEMA_VERSION = 1;
+
+export const WORKFLOW_STATUSES = Object.freeze([
+  'NEW',
+  'READY',
+  'ACTIVE',
+  'COMPLETE',
+  'INTERRUPTED',
+  'BLOCKED',
+]);
+
+export const BLOCKER_TYPES = Object.freeze([
+  'authorization',
+  'business-rule',
+  'evidence',
+  'external-decision',
+  'other',
+]);
+
+export const SKIP_POLICIES = Object.freeze([
+  'adaptive-skip',
+  'known-root-cause',
+  'readiness-only',
+  'no-ops-authority',
+  'no-security-risk',
+  'behavior-defined',
+  'local-low-risk',
+  'no-ux-decision',
+]);
+
+export const SKIP_REASONS = Object.freeze([
+  'behavior-defined',
+  'local-low-risk',
+  'no-ux-decision',
+  'known-root-cause',
+  'readiness-only',
+  'no-ops-authority',
+  'no-security-risk',
+]);
+
+const FORBIDDEN_AUTHORITY_KEYS = Object.freeze([
+  'primarycapability',
+  'authorizedaction',
+  'mutationpermission',
+  'routeauthority',
+  'governingaction',
+  'cachedauthority',
+  'authoritydecision',
+]);
+
+const STALE_REASONS = Object.freeze([
+  'workflow-no-longer-applicable',
+  'primary-skill-shifted',
+  'verification-evidence-stale',
+]);
+
+const HIGH_SENSITIVITY_KINDS = new Set([
+  'change-implemented',
+  'targeted-tests-passed',
+  'relevant-suite-passed',
+  'build-passed',
+  'package-verified',
+  'compatibility-verified',
+  'regression-proof-added',
+  'release-readiness-verified',
+]);
+
+const MEDIUM_SENSITIVITY_KINDS = new Set([
+  'failure-reproduced',
+  'typecheck-passed',
+  'lint-passed',
+  'security-reviewed',
+]);
+
+const RECEIPT_KEYS = new Set(['kind', 'quality', 'source', 'detail', 'timestamp', 'provenance']);
+const SKIPPED_KEYS = new Set(['stage', 'reason', 'evidence', 'policy', 'skippedAt']);
+const COMPLETED_KEYS = new Set(['stage', 'completedAt', 'evidenceReceipts', 'stopConditionMet']);
+const BLOCKER_KEYS = new Set(['id', 'reason', 'type', 'detail', 'blockedAt']);
+
+const WORKFLOW_IDS = new Set(WORKFLOW_SKILLS.map((w) => w.id));
+const PRIMITIVE_IDS = new Set(SKILLS.map((s) => s.id));
+
+const SELECTABLE_STAGES = Object.freeze({
+  'showdar-feature': ['showdar-understand', 'showdar-requirements', 'showdar-plan', 'showdar-design', 'showdar-build', 'showdar-test', 'showdar-review'],
+  'showdar-bugfix': ['showdar-understand', 'showdar-debug', 'showdar-build', 'showdar-test', 'showdar-review'],
+  'showdar-release': ['showdar-quality', 'showdar-security', 'showdar-ship', 'showdar-ops'],
+  'showdar-incident': ['showdar-understand', 'showdar-debug', 'showdar-recover', 'showdar-test', 'showdar-ops'],
+});
+
+const SKIP_RULES = Object.freeze({
+  'showdar-feature': Object.freeze({
+    'showdar-requirements': { reason: 'behavior-defined', policy: 'behavior-defined', evidence: ['behavior-defined'] },
+    'showdar-plan': { reason: 'local-low-risk', policy: 'local-low-risk', evidence: ['architecture-understood'] },
+    'showdar-design': { reason: 'no-ux-decision', policy: 'no-ux-decision', evidence: [] },
+  }),
+  'showdar-bugfix': Object.freeze({
+    'showdar-debug': { reason: 'known-root-cause', policy: 'known-root-cause', evidence: ['root-cause-proven'] },
+  }),
+  'showdar-release': Object.freeze({
+    'showdar-security': { reason: 'no-security-risk', policy: 'no-security-risk', evidence: [] },
+    'showdar-ops': { reason: 'readiness-only', policy: 'readiness-only', evidence: [] },
+  }),
+  'showdar-incident': Object.freeze({
+    'showdar-ops': { reason: 'no-ops-authority', policy: 'no-ops-authority', evidence: [] },
+  }),
+});
+
+const REQUIRED_STAGES = Object.freeze({
+  'showdar-feature': ['showdar-understand', 'showdar-build', 'showdar-test', 'showdar-review'],
+  'showdar-bugfix': ['showdar-understand', 'showdar-test', 'showdar-review'],
+  'showdar-release': ['showdar-quality', 'showdar-ship'],
+  'showdar-incident': ['showdar-understand', 'showdar-debug', 'showdar-recover', 'showdar-test'],
+});
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isIsoString(value) {
+  return typeof value === 'string' && !Number.isNaN(Date.parse(value));
+}
+
+function containsForbiddenAuthorityKey(value, path = '$') {
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const hit = containsForbiddenAuthorityKey(value[i], `${path}[${i}]`);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  if (isRecord(value)) {
+    for (const key of Object.keys(value)) {
+      const normalized = String(key).toLowerCase().replace(/[\s_-]+/g, '');
+      if (FORBIDDEN_AUTHORITY_KEYS.some((f) => normalized.includes(f))) return `${path}.${key}`;
+      const hit = containsForbiddenAuthorityKey(value[key], `${path}.${key}`);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+function validateReceipt(entry) {
+  const errors = [];
+  if (!isRecord(entry)) return ['evidence receipt must be an object'];
+  if (!EVIDENCE_KINDS.includes(entry.kind)) errors.push(`receipt kind must be one of: ${EVIDENCE_KINDS.join(', ')}`);
+  if (!EVIDENCE_QUALITIES.includes(entry.quality)) errors.push(`receipt quality must be one of: ${EVIDENCE_QUALITIES.join(', ')}`);
+  if (typeof entry.source !== 'string' || !PRIMITIVE_IDS.has(entry.source)) errors.push('receipt source must be a known primitive skill id');
+  if (typeof entry.detail !== 'string' || !entry.detail.trim()) errors.push('receipt detail must be a non-empty string');
+  if (!isIsoString(entry.timestamp)) errors.push('receipt timestamp must be ISO8601');
+  if (entry.provenance !== undefined && !isRecord(entry.provenance)) errors.push('receipt provenance must be an object');
+  for (const key of Object.keys(entry)) {
+    if (!RECEIPT_KEYS.has(key)) errors.push(`receipt contains unknown key: ${key}`);
+  }
+  return errors;
+}
+
+function validateSkipped(entry, workflowId, selectedStages) {
+  const errors = [];
+  if (!isRecord(entry)) return ['skipped stage must be an object'];
+  const catalogStages = SELECTABLE_STAGES[workflowId] ?? [];
+  if (typeof entry.stage !== 'string' || !catalogStages.includes(entry.stage)) errors.push(`skipped stage must be a catalog stage of ${workflowId}`);
+  if (selectedStages.includes(entry.stage)) errors.push(`skipped stage ${entry.stage} must not be selected`);
+  if (!SKIP_REASONS.includes(entry.reason)) errors.push(`skip reason must be one of: ${SKIP_REASONS.join(', ')}`);
+  if (!Array.isArray(entry.evidence) || entry.evidence.some((e) => typeof e !== 'string')) errors.push('skip evidence must be an array of strings');
+  if (!SKIP_POLICIES.includes(entry.policy)) errors.push(`skip policy must be one of: ${SKIP_POLICIES.join(', ')}`);
+  if (!isIsoString(entry.skippedAt)) errors.push('skip skippedAt must be ISO8601');
+  for (const key of Object.keys(entry)) {
+    if (!SKIPPED_KEYS.has(key)) errors.push(`skipped stage contains unknown key: ${key}`);
+  }
+  const rule = (SKIP_RULES[workflowId] ?? {})[entry.stage];
+  if (!rule) errors.push(`stage ${entry.stage} is not skippable under ${workflowId} policy`);
+  else {
+    if (entry.reason !== rule.reason) errors.push(`skip reason for ${entry.stage} must be ${rule.reason}`);
+    if (entry.policy !== rule.policy) errors.push(`skip policy for ${entry.stage} must be ${rule.policy}`);
+  }
+  return errors;
+}
+
+function validateCompleted(entry, selectedStages) {
+  const errors = [];
+  if (!isRecord(entry)) return ['completed stage must be an object'];
+  if (typeof entry.stage !== 'string' || !selectedStages.includes(entry.stage)) errors.push('completed stage must be a selected stage');
+  if (!isIsoString(entry.completedAt)) errors.push('completed completedAt must be ISO8601');
+  if (!Array.isArray(entry.evidenceReceipts) || !entry.evidenceReceipts.length) errors.push('completed evidenceReceipts must be a non-empty array');
+  else for (const receipt of entry.evidenceReceipts) errors.push(...validateReceipt(receipt).map((e) => `completed ${entry.stage}: ${e}`));
+  if (typeof entry.stopConditionMet !== 'boolean') errors.push('completed stopConditionMet must be boolean');
+  for (const key of Object.keys(entry)) {
+    if (!COMPLETED_KEYS.has(key)) errors.push(`completed stage contains unknown key: ${key}`);
+  }
+  return errors;
+}
+
+function validateBlocker(blocker) {
+  const errors = [];
+  if (!isRecord(blocker)) return ['blocker must be an object'];
+  if (typeof blocker.id !== 'string' || !blocker.id.trim()) errors.push('blocker id must be a non-empty string');
+  if (typeof blocker.reason !== 'string' || !blocker.reason.trim()) errors.push('blocker reason must be a non-empty string');
+  if (!BLOCKER_TYPES.includes(blocker.type)) errors.push(`blocker type must be one of: ${BLOCKER_TYPES.join(', ')}`);
+  if (blocker.detail !== undefined && typeof blocker.detail !== 'string') errors.push('blocker detail must be a string');
+  if (!isIsoString(blocker.blockedAt)) errors.push('blocker blockedAt must be ISO8601');
+  for (const key of Object.keys(blocker)) {
+    if (!BLOCKER_KEYS.has(key)) errors.push(`blocker contains unknown key: ${key}`);
+  }
+  return errors;
+}
+
+function uniqueSortedStages(stages) {
+  return [...new Set(stages)].sort();
+}
+
+function computeNext(selectedStages, completedStages, skippedStages) {
+  const done = new Set([...completedStages.map((c) => c.stage), ...skippedStages.map((s) => s.stage)]);
+  return selectedStages.find((s) => !done.has(s)) ?? null;
+}
+
+function now() {
+  return new Date().toISOString();
+}
+
+function freezeState(state) {
+  return Object.freeze({
+    ...state,
+    candidateStages: Object.freeze([...state.candidateStages]),
+    selectedStages: Object.freeze([...state.selectedStages]),
+    completedStages: Object.freeze(state.completedStages.map((c) => Object.freeze({ ...c, evidenceReceipts: Object.freeze(c.evidenceReceipts.map((r) => Object.freeze({ ...r }))) }))),
+    skippedStages: Object.freeze(state.skippedStages.map((s) => Object.freeze({ ...s, evidence: Object.freeze([...s.evidence]) }))),
+    evidenceReceipts: Object.freeze(state.evidenceReceipts.map((r) => Object.freeze({ ...r }))),
+    blockers: Object.freeze(state.blockers.map((b) => Object.freeze({ ...b }))),
+  });
+}
+
+function bump(state, patch) {
+  const next = {
+    ...state,
+    ...patch,
+    revision: state.revision + 1,
+    updatedAt: now(),
+  };
+  next.nextStage = computeNext(next.selectedStages, next.completedStages, next.skippedStages);
+  return freezeState(next);
+}
+
+export function validateWorkflowState(input) {
+  const errors = [];
+  if (!isRecord(input)) return { ok: false, errors: ['workflow state must be an object'] };
+  const forbidden = containsForbiddenAuthorityKey(input);
+  if (forbidden) errors.push(`workflow state must not persist authority-derived fields (found at ${forbidden})`);
+  if (input.schemaVersion !== WORKFLOW_SCHEMA_VERSION) errors.push(`schemaVersion must be ${WORKFLOW_SCHEMA_VERSION}`);
+  if (typeof input.workflowId !== 'string' || !WORKFLOW_IDS.has(input.workflowId)) errors.push(`workflowId must be one of: ${[...WORKFLOW_IDS].join(', ')}`);
+  if (!WORKFLOW_STATUSES.includes(input.status)) errors.push(`status must be one of: ${WORKFLOW_STATUSES.join(', ')}`);
+  if (!Number.isInteger(input.revision) || input.revision < 0) errors.push('revision must be a non-negative integer');
+  if (!isIsoString(input.createdAt)) errors.push('createdAt must be ISO8601');
+  if (!isIsoString(input.updatedAt)) errors.push('updatedAt must be ISO8601');
+  if (!Array.isArray(input.candidateStages) || input.candidateStages.some((s) => !PRIMITIVE_IDS.has(s))) errors.push('candidateStages must be known primitive skill ids');
+  if (!Array.isArray(input.selectedStages) || input.selectedStages.some((s) => !PRIMITIVE_IDS.has(s))) errors.push('selectedStages must be known primitive skill ids');
+  if (new Set(input.selectedStages ?? []).size !== (input.selectedStages ?? []).length) errors.push('selectedStages must not contain duplicates');
+
+  const workflowId = input.workflowId;
+  const catalogStages = workflowId && SELECTABLE_STAGES[workflowId] ? SELECTABLE_STAGES[workflowId] : [];
+  if (Array.isArray(input.candidateStages) && catalogStages.length) {
+    for (const stage of input.candidateStages) {
+      if (!catalogStages.includes(stage)) errors.push(`candidate stage ${stage} is not declared by ${workflowId}`);
+    }
+  }
+  if (Array.isArray(input.selectedStages) && Array.isArray(input.candidateStages)) {
+    for (const stage of input.selectedStages) {
+      if (!input.candidateStages.includes(stage)) errors.push(`selected stage ${stage} must be a candidate stage`);
+    }
+  }
+  if (input.activeStage !== null && input.activeStage !== undefined) {
+    if (typeof input.activeStage !== 'string' || !(input.selectedStages ?? []).includes(input.activeStage)) errors.push('activeStage must be a selected stage or null');
+  }
+  if (input.nextStage !== null && input.nextStage !== undefined) {
+    if (typeof input.nextStage !== 'string' || !(input.selectedStages ?? []).includes(input.nextStage)) errors.push('nextStage must be a selected stage or null');
+  }
+  if (!Array.isArray(input.completedStages)) errors.push('completedStages must be an array');
+  else for (const entry of input.completedStages) errors.push(...validateCompleted(entry, input.selectedStages ?? []));
+  if (!Array.isArray(input.skippedStages)) errors.push('skippedStages must be an array');
+  else for (const entry of input.skippedStages) errors.push(...validateSkipped(entry, workflowId, input.selectedStages ?? []));
+  if (!Array.isArray(input.evidenceReceipts)) errors.push('evidenceReceipts must be an array');
+  else for (const receipt of input.evidenceReceipts) errors.push(...validateReceipt(receipt));
+  if (!Array.isArray(input.blockers)) errors.push('blockers must be an array');
+  else for (const blocker of input.blockers) errors.push(...validateBlocker(blocker));
+
+  const accounted = new Set([...(input.completedStages ?? []).map((c) => c.stage), ...(input.skippedStages ?? []).map((s) => s.stage)]);
+  if ((input.completedStages ?? []).some((c, i, arr) => arr.findIndex((x) => x.stage === c.stage) !== i)) errors.push('completedStages must not contain duplicate stages');
+  if ((input.skippedStages ?? []).some((s, i, arr) => arr.findIndex((x) => x.stage === s.stage) !== i)) errors.push('skippedStages must not contain duplicate stages');
+  for (const stage of accounted) {
+    if (!(input.selectedStages ?? []).includes(stage) && !(input.skippedStages ?? []).some((s) => s.stage === stage)) {
+      errors.push(`completed stage ${stage} must be selected`);
+    }
+  }
+  const expectedNext = Array.isArray(input.selectedStages) ? computeNext(input.selectedStages, input.completedStages ?? [], input.skippedStages ?? []) : null;
+  if ((input.nextStage ?? null) !== expectedNext) errors.push(`nextStage must be ${expectedNext ?? 'null'}`);
+  if (input.status === 'ACTIVE' && (input.activeStage === null || input.activeStage === undefined)) errors.push('ACTIVE status requires an activeStage');
+  if (input.status !== 'ACTIVE' && input.activeStage !== null && input.activeStage !== undefined && (input.completedStages ?? []).some((c) => c.stage === input.activeStage)) errors.push('activeStage must not be completed');
+  return { ok: errors.length === 0, errors };
+}
+
+export function createWorkflowState(workflowId, options = {}) {
+  const errors = [];
+  if (!WORKFLOW_IDS.has(workflowId)) return { ok: false, errors: [`workflowId must be one of: ${[...WORKFLOW_IDS].join(', ')}`] };
+  const catalogStages = [...SELECTABLE_STAGES[workflowId]];
+  const candidates = options.candidateStages ?? catalogStages;
+  if (!Array.isArray(candidates) || !candidates.length) errors.push('candidateStages must be a non-empty array');
+  for (const stage of candidates ?? []) {
+    if (!catalogStages.includes(stage)) errors.push(`candidate stage ${stage} is not declared by ${workflowId}`);
+  }
+  const selected = options.selectedStages ?? candidates;
+  if (!Array.isArray(selected) || !selected.length) errors.push('selectedStages must be a non-empty array');
+  for (const stage of selected ?? []) {
+    if (!(candidates ?? []).includes(stage)) errors.push(`selected stage ${stage} must be a candidate stage`);
+  }
+  for (const required of REQUIRED_STAGES[workflowId]) {
+    if (!(selected ?? []).includes(required) && !((options.skippedStages ?? []).some((s) => s.stage === required))) {
+      errors.push(`required stage ${required} must be selected or explicitly skipped under policy`);
+    }
+  }
+  if (errors.length) return { ok: false, errors };
+  const timestamp = now();
+  const state = {
+    schemaVersion: WORKFLOW_SCHEMA_VERSION,
+    workflowId,
+    candidateStages: [...candidates],
+    selectedStages: [...selected],
+    activeStage: null,
+    completedStages: [],
+    skippedStages: (options.skippedStages ?? []).map((s) => ({ ...s, evidence: [...(s.evidence ?? [])] })),
+    evidenceReceipts: [],
+    blockers: [],
+    nextStage: null,
+    status: 'NEW',
+    revision: 0,
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  };
+  state.nextStage = computeNext(state.selectedStages, state.completedStages, state.skippedStages);
+  for (const skipped of state.skippedStages) {
+    const skippedErrors = validateSkipped({ ...skipped, skippedAt: skipped.skippedAt ?? timestamp }, workflowId, state.selectedStages);
+    if (skippedErrors.length) return { ok: false, errors: skippedErrors };
+  }
+  const validation = validateWorkflowState(freezeState(state));
+  if (!validation.ok) return validation;
+  return { ok: true, errors: [], value: freezeState({ ...state, status: 'READY', nextStage: state.nextStage }) };
+}
+
+export function startStage(state, stage) {
+  if (state.status === 'COMPLETE') throw new Error('cannot start a stage on a COMPLETE workflow');
+  if (state.status === 'INTERRUPTED') throw new Error('cannot start a stage on an INTERRUPTED workflow; resume first');
+  if (state.status !== 'READY') throw new Error(`startStage requires READY status; got ${state.status}`);
+  if (state.blockers.length > 0) throw new Error('cannot start a stage while blockers remain');
+  if (stage !== state.nextStage) throw new Error(`stage ${stage} is not next; expected ${state.nextStage ?? 'null'}`);
+  return bump(state, { status: 'ACTIVE', activeStage: stage });
+}
+
+export function completeStage(state, stage, receipts) {
+  if (state.status !== 'ACTIVE') throw new Error(`completeStage requires ACTIVE status; got ${state.status}`);
+  if (stage !== state.activeStage) throw new Error(`stage ${stage} is not active; active is ${state.activeStage ?? 'null'}`);
+  if (!Array.isArray(receipts) || !receipts.length) throw new Error('completeStage requires at least one evidence receipt');
+  const stamped = receipts.map((r) => ({ ...r, timestamp: r.timestamp ?? now() }));
+  for (const receipt of stamped) {
+    const receiptErrors = validateReceipt(receipt);
+    if (receiptErrors.length) throw new Error(`Invalid evidence receipt: ${receiptErrors.join('; ')}`);
+    if (receipt.source !== stage) throw new Error(`receipt source ${receipt.source} must match completing stage ${stage}`);
+  }
+  const qualities = stamped.map((r) => r.quality);
+  if (qualities.some((q) => q === 'failed' || q === 'missing')) throw new Error('completeStage requires receipts with observed or verified quality');
+  if (!qualities.some((q) => q === 'observed' || q === 'verified')) throw new Error('completeStage requires at least one observed or verified receipt');
+  const completedEntry = {
+    stage,
+    completedAt: now(),
+    evidenceReceipts: stamped,
+    stopConditionMet: true,
+  };
+  return bump(state, {
+    status: 'READY',
+    activeStage: null,
+    completedStages: [...state.completedStages, completedEntry],
+    evidenceReceipts: [...state.evidenceReceipts, ...stamped].sort((a, b) => a.kind.localeCompare(b.kind)),
+  });
+}
+
+export function skipStage(state, stage, { reason, evidence = [], policy } = {}) {
+  if (state.status === 'COMPLETE') throw new Error('cannot skip a stage on a COMPLETE workflow');
+  if (state.status !== 'READY') throw new Error(`skipStage requires READY status; got ${state.status}`);
+  if (!SELECTABLE_STAGES[state.workflowId]?.includes(stage)) throw new Error(`stage ${stage} is not declared by ${state.workflowId}`);
+  if (state.selectedStages.includes(stage)) throw new Error(`stage ${stage} is selected and cannot be skipped; remove from selection at creation`);
+  if (state.completedStages.some((c) => c.stage === stage) || state.skippedStages.some((s) => s.stage === stage)) throw new Error(`stage ${stage} is already accounted`);
+  const rule = (SKIP_RULES[state.workflowId] ?? {})[stage];
+  if (!rule) throw new Error(`stage ${stage} is not skippable under ${state.workflowId} policy`);
+  if (reason !== rule.reason) throw new Error(`skip reason for ${stage} must be ${rule.reason}`);
+  if (policy !== rule.policy) throw new Error(`skip policy for ${stage} must be ${rule.policy}`);
+  for (const required of rule.evidence) {
+    const found = [...state.evidenceReceipts, ...(evidenceReceiptsFromArray(evidence) ?? [])].some((r) => r.kind === required && ['observed', 'verified'].includes(r.quality));
+    if (!found) throw new Error(`skip of ${stage} requires evidence ${required} with observed or verified quality`);
+  }
+  const skipped = {
+    stage,
+    reason,
+    evidence: [...evidence.map((e) => (typeof e === 'string' ? e : e.kind))],
+    policy,
+    skippedAt: now(),
+  };
+  return bump(state, { skippedStages: [...state.skippedStages, skipped] });
+}
+
+function evidenceReceiptsFromArray(evidence) {
+  if (!Array.isArray(evidence)) return [];
+  return evidence.filter((e) => isRecord(e) && typeof e.kind === 'string');
+}
+
+export function recordEvidence(state, receipt) {
+  const stamped = { ...receipt, timestamp: receipt.timestamp ?? now() };
+  const receiptErrors = validateReceipt(stamped);
+  if (receiptErrors.length) throw new Error(`Invalid evidence receipt: ${receiptErrors.join('; ')}`);
+  const existingIdx = state.evidenceReceipts.findIndex((r) => r.kind === stamped.kind);
+  const order = { claimed: 0, observed: 1, verified: 2 };
+  let next = [...state.evidenceReceipts];
+  if (existingIdx >= 0) {
+    const existing = next[existingIdx];
+    const incomingNegative = stamped.quality === 'failed' || stamped.quality === 'missing';
+    const existingNegative = existing.quality === 'failed' || existing.quality === 'missing';
+    let keepExisting;
+    if (incomingNegative) keepExisting = false;
+    else if (existingNegative) keepExisting = false;
+    else keepExisting = (order[existing.quality] ?? 0) >= (order[stamped.quality] ?? 0);
+    next[existingIdx] = keepExisting ? existing : stamped;
+  } else {
+    next = [...next, stamped].sort((a, b) => a.kind.localeCompare(b.kind));
+  }
+  return bump(state, { evidenceReceipts: next });
+}
+
+export function addWorkflowBlocker(state, blocker) {
+  if (state.status === 'COMPLETE') throw new Error('cannot add a blocker to a COMPLETE workflow');
+  if (state.status !== 'ACTIVE' && state.status !== 'READY' && state.status !== 'BLOCKED') throw new Error(`addBlocker requires ACTIVE, READY, or BLOCKED status; got ${state.status}`);
+  if (state.blockers.some((b) => b.id === blocker.id)) return state;
+  const stamped = { ...blocker, blockedAt: blocker.blockedAt ?? now() };
+  const blockerErrors = validateBlocker(stamped);
+  if (blockerErrors.length) throw new Error(`Invalid blocker: ${blockerErrors.join('; ')}`);
+  const blockers = [...state.blockers, stamped].sort((a, b) => a.id.localeCompare(b.id));
+  return bump(state, { status: 'BLOCKED', blockers });
+}
+
+export function removeWorkflowBlocker(state, blockerId) {
+  if (state.status === 'COMPLETE') throw new Error('cannot remove a blocker from a COMPLETE workflow');
+  const next = state.blockers.filter((b) => b.id !== blockerId);
+  if (next.length === state.blockers.length) return state;
+  const status = state.status === 'BLOCKED' && next.length === 0 ? 'READY' : state.status;
+  if (status === 'BLOCKED') return bump(state, { blockers: next });
+  return bump({ ...state, status: state.status === 'BLOCKED' && next.length > 0 ? 'BLOCKED' : state.status }, { blockers: next, status: next.length === 0 && state.status === 'BLOCKED' ? 'READY' : state.status });
+}
+
+export function interruptWorkflow(state, reason) {
+  if (state.status === 'COMPLETE') throw new Error('cannot interrupt a COMPLETE workflow');
+  if (state.status === 'INTERRUPTED') return state;
+  if (state.status !== 'ACTIVE' && state.status !== 'READY' && state.status !== 'BLOCKED') throw new Error(`interrupt requires ACTIVE, READY, or BLOCKED status; got ${state.status}`);
+  if (typeof reason !== 'string' || !reason.trim()) throw new Error('interrupt reason must be a non-empty string');
+  return bump(state, { status: 'INTERRUPTED', activeStage: state.status === 'ACTIVE' ? null : state.activeStage });
+}
+
+export function isStageComplete(primitiveSkill, receipts) {
+  const conditions = getStopConditions(primitiveSkill);
+  if (!conditions.length) return receipts.length > 0;
+  return true;
+}
+
+export function isWorkflowComplete(state) {
+  const allAccounted = state.selectedStages.every((s) =>
+    state.completedStages.some((c) => c.stage === s) || state.skippedStages.some((k) => k.stage === s),
+  );
+  if (!allAccounted) return false;
+  if (state.blockers.length > 0) return false;
+  return state.nextStage === null;
+}
+
+export function finalizeWorkflow(state) {
+  if (state.status === 'COMPLETE') return state;
+  if (state.status !== 'READY') throw new Error(`finalize requires READY status; got ${state.status}`);
+  if (!isWorkflowComplete(state)) throw new Error('workflow completion requires every selected stage completed or validly skipped with no blockers');
+  const negative = state.evidenceReceipts.filter((r) => r.quality === 'failed' || r.quality === 'missing');
+  if (negative.length) throw new Error(`workflow completion blocked by negative evidence: ${negative.map((r) => r.kind).join(', ')}`);
+  return bump({ ...state, nextStage: null }, { status: 'COMPLETE', activeStage: null });
+}
+
+export function serializeWorkflowState(state) {
+  const validation = validateWorkflowState(state);
+  if (!validation.ok) throw new Error(`Cannot serialize invalid workflow state: ${validation.errors.join('; ')}`);
+  return JSON.stringify(state, null, 2);
+}
+
+export function deserializeWorkflowState(input) {
+  let parsed = input;
+  if (typeof input === 'string') {
+    try {
+      parsed = JSON.parse(input);
+    } catch (error) {
+      throw new Error(`Invalid workflow checkpoint JSON: ${error.message}`);
+    }
+  }
+  const before = JSON.stringify(parsed);
+  const validation = validateWorkflowState(parsed);
+  if (!validation.ok) throw new Error(`Invalid workflow checkpoint: ${validation.errors.join('; ')}`);
+  const frozen = freezeState(JSON.parse(JSON.stringify(parsed)));
+  if (JSON.stringify(frozen) !== before && JSON.stringify(JSON.parse(JSON.stringify(parsed))) !== before) {
+    throw new Error('Invalid workflow checkpoint: non-deterministic representation');
+  }
+  return frozen;
+}
+
+export function isFreshnessSensitive(kind) {
+  return HIGH_SENSITIVITY_KINDS.has(kind) || MEDIUM_SENSITIVITY_KINDS.has(kind);
+}
+
+export function isHighSensitivity(kind) {
+  return HIGH_SENSITIVITY_KINDS.has(kind);
+}
+
+export function requiresReverification(kind) {
+  return HIGH_SENSITIVITY_KINDS.has(kind);
+}
+
+function workflowApplicableSkill(workflowId, primarySkill) {
+  return (SELECTABLE_STAGES[workflowId] ?? []).includes(primarySkill);
+}
+
+export function checkStaleCheckpoint(state, resolution) {
+  if (!isRecord(resolution) || !isRecord(resolution.primary) || typeof resolution.primary.skill !== 'string') {
+    return { stale: true, reason: 'workflow-no-longer-applicable', detail: 'resolution is missing a primary skill' };
+  }
+  if (!workflowApplicableSkill(state.workflowId, resolution.primary.skill)) {
+    return { stale: true, reason: 'workflow-no-longer-applicable', detail: `primary ${resolution.primary.skill} is not a stage of ${state.workflowId}` };
+  }
+  const expectedPrimary = state.activeStage ?? state.nextStage ?? SELECTABLE_STAGES[state.workflowId][0];
+  if (resolution.primary.skill !== expectedPrimary) {
+    return { stale: true, reason: 'primary-skill-shifted', detail: `expected ${expectedPrimary}, got ${resolution.primary.skill}` };
+  }
+  const required = resolution.verificationPlan?.required ?? [];
+  for (const check of required) {
+    const evidenceKind = checkToEvidence(check);
+    if (!evidenceKind) continue;
+    const receipt = state.evidenceReceipts.find((r) => r.kind === evidenceKind);
+    if (receipt && isHighSensitivity(evidenceKind)) {
+      return { stale: true, reason: 'verification-evidence-stale', detail: `required check ${check} maps to high-sensitivity evidence ${evidenceKind} which must be re-verified` };
+    }
+  }
+  return { stale: false };
+}
+
+function checkToEvidence(check) {
+  const mapping = {
+    'targeted-test': 'targeted-tests-passed',
+    'relevant-suite': 'relevant-suite-passed',
+    'typecheck': 'typecheck-passed',
+    'lint': 'lint-passed',
+    'build': 'build-passed',
+    'package': 'package-verified',
+    'compatibility': 'compatibility-verified',
+    'security': 'security-reviewed',
+    'regression': 'regression-proof-added',
+    'release-readiness': 'release-readiness-verified',
+    'deployment-safety': 'deployment-verified',
+  };
+  return mapping[check] ?? null;
+}
+
+export function resumeFromCheckpoint(checkpoint, resolution) {
+  const state = deserializeWorkflowState(checkpoint);
+  if (state.status !== 'INTERRUPTED' && state.status !== 'BLOCKED') {
+    throw new Error(`resume requires INTERRUPTED or BLOCKED status; got ${state.status}`);
+  }
+  const stale = checkStaleCheckpoint(state, resolution);
+  if (stale.stale) {
+    const blocked = bump({ ...state, status: state.status }, {
+      status: 'BLOCKED',
+      blockers: state.blockers.some((b) => b.id === 'stale-checkpoint')
+        ? state.blockers
+        : [...state.blockers, { id: 'stale-checkpoint', reason: stale.reason, type: 'evidence', detail: stale.detail ?? stale.reason, blockedAt: now() }].sort((a, b) => a.id.localeCompare(b.id)),
+    });
+    return { state: blocked, replanRequired: true, reason: stale.reason, detail: stale.detail };
+  }
+  if (state.status === 'INTERRUPTED') {
+    return { state: bump(state, { status: 'READY' }), replanRequired: false };
+  }
+  if (state.status === 'BLOCKED' && state.blockers.length === 0) {
+    return { state: bump(state, { status: 'READY' }), replanRequired: false };
+  }
+  return { state, replanRequired: false };
+}
+
+export function selectableStages(workflowId) {
+  return [...(SELECTABLE_STAGES[workflowId] ?? [])];
+}
+
+export function skipRule(workflowId, stage) {
+  return (SKIP_RULES[workflowId] ?? {})[stage] ?? null;
+}
+
+export function requiredStages(workflowId) {
+  return [...(REQUIRED_STAGES[workflowId] ?? [])];
+}
+
+export { STALE_REASONS, FORBIDDEN_AUTHORITY_KEYS, HIGH_SENSITIVITY_KINDS, MEDIUM_SENSITIVITY_KINDS, SELECTABLE_STAGES, SKIP_RULES, uniqueSortedStages, getWorkflow };
+
+export const workflowStateAPI = {
+  createWorkflowState,
+  startStage,
+  completeStage,
+  skipStage,
+  recordEvidence,
+  addWorkflowBlocker,
+  removeWorkflowBlocker,
+  interruptWorkflow,
+  isStageComplete,
+  isWorkflowComplete,
+  finalizeWorkflow,
+  serializeWorkflowState,
+  deserializeWorkflowState,
+  validateWorkflowState,
+  checkStaleCheckpoint,
+  resumeFromCheckpoint,
+  isFreshnessSensitive,
+  isHighSensitivity,
+  requiresReverification,
+};

package/src/workflow-trace.js

@@ -0,0 +1,183 @@
+import {
+  validateWorkflowState,
+  isWorkflowComplete,
+  FORBIDDEN_AUTHORITY_KEYS,
+} from './workflow-state.js';
+
+export const WORKFLOW_EVENT_TYPES = Object.freeze([
+  'workflow-created',
+  'stages-selected',
+  'stage-entered',
+  'evidence-recorded',
+  'stage-completed',
+  'stage-skipped',
+  'workflow-blocked',
+  'workflow-interrupted',
+  'workflow-resumed',
+  'workflow-completed',
+]);
+
+const EVENT_TYPE_SET = new Set(WORKFLOW_EVENT_TYPES);
+const EVENT_KEYS = new Set(['seq', 'type', 'workflowId', 'revision', 'stage', 'detail']);
+
+function sortedKinds(receipts) {
+  return [...receipts].map((r) => r.kind).sort();
+}
+
+function sortedQualities(receipts) {
+  return [...receipts].map((r) => r.quality).sort();
+}
+
+function freezeEvent(event) {
+  return Object.freeze({ ...event, detail: Object.freeze({ ...event.detail }) });
+}
+
+function makeEvent(seq, type, state, stage, detail) {
+  return freezeEvent({
+    seq,
+    type,
+    workflowId: state.workflowId,
+    revision: state.revision,
+    stage: stage ?? null,
+    detail: detail ?? {},
+  });
+}
+
+export function assertNoAuthority(event) {
+  const serialized = JSON.stringify(event).toLowerCase().replace(/[\s_-]+/g, '');
+  for (const forbidden of FORBIDDEN_AUTHORITY_KEYS) {
+    if (serialized.includes(forbidden)) {
+      throw new Error(`workflow trace event must not contain authority-derived content (found ${forbidden})`);
+    }
+  }
+  return true;
+}
+
+export function validateWorkflowEvent(event) {
+  const errors = [];
+  if (event === null || typeof event !== 'object' || Array.isArray(event)) return { ok: false, errors: ['workflow event must be an object'] };
+  for (const key of Object.keys(event)) {
+    if (!EVENT_KEYS.has(key)) errors.push(`event contains unknown key: ${key}`);
+  }
+  if (!Number.isInteger(event.seq) || event.seq < 0) errors.push('event seq must be a non-negative integer');
+  if (!EVENT_TYPE_SET.has(event.type)) errors.push(`event type must be one of: ${WORKFLOW_EVENT_TYPES.join(', ')}`);
+  if (typeof event.workflowId !== 'string' || !event.workflowId) errors.push('event workflowId must be a non-empty string');
+  if (!Number.isInteger(event.revision) || event.revision < 0) errors.push('event revision must be a non-negative integer');
+  if (event.stage !== null && typeof event.stage !== 'string') errors.push('event stage must be a string or null');
+  if (event.detail === null || typeof event.detail !== 'object' || Array.isArray(event.detail)) errors.push('event detail must be an object');
+  if (!errors.length) {
+    try {
+      assertNoAuthority(event);
+    } catch (error) {
+      errors.push(error.message);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function eventKey(event) {
+  return JSON.stringify([event.type, event.workflowId, event.stage, event.detail]);
+}
+
+export function normalizeTrace(events) {
+  return events.map(eventKey);
+}
+
+function requireValidState(state, label) {
+  const validation = validateWorkflowState(state);
+  if (!validation.ok) throw new Error(`Invalid ${label} workflow state: ${validation.errors.join('; ')}`);
+}
+
+export function projectWorkflowEvents(prevState, nextState, input = {}) {
+  if (prevState !== null) requireValidState(prevState, 'prev');
+  requireValidState(nextState, 'next');
+  const op = input.op ?? null;
+  if (typeof op !== 'string' || !op) throw new Error('projectWorkflowEvents requires input.op');
+  const events = [];
+  const emit = (type, stage, detail) => {
+    const event = makeEvent(events.length, type, nextState, stage, detail);
+    const validation = validateWorkflowEvent(event);
+    if (!validation.ok) throw new Error(`Projected invalid event: ${validation.errors.join('; ')}`);
+    events.push(event);
+  };
+  switch (op) {
+    case 'create': {
+      emit('workflow-created', null, {
+        selectedStages: [...nextState.selectedStages],
+        candidateStages: [...nextState.candidateStages],
+      });
+      const sameOrder = nextState.selectedStages.length === nextState.candidateStages.length
+        && nextState.selectedStages.every((s, i) => s === nextState.candidateStages[i]);
+      if (!sameOrder) emit('stages-selected', null, { selectedStages: [...nextState.selectedStages] });
+      break;
+    }
+    case 'start':
+      emit('stage-entered', input.stage ?? nextState.activeStage, {});
+      break;
+    case 'record': {
+      const receipts = input.receipts ?? nextState.evidenceReceipts.slice(-1);
+      emit('evidence-recorded', null, { receiptKinds: sortedKinds(receipts), receiptQualities: sortedQualities(receipts) });
+      break;
+    }
+    case 'complete': {
+      const entry = nextState.completedStages[nextState.completedStages.length - 1];
+      if (!entry) throw new Error('complete projection requires a completed stage entry');
+      emit('stage-completed', entry.stage, {
+        receiptKinds: sortedKinds(entry.evidenceReceipts),
+        receiptQualities: sortedQualities(entry.evidenceReceipts),
+      });
+      if (nextState.nextStage === null && isWorkflowComplete(nextState)) {
+        emit('workflow-completed', null, {
+          completedStages: nextState.completedStages.map((c) => c.stage),
+          skippedStages: nextState.skippedStages.map((s) => s.stage),
+        });
+      }
+      break;
+    }
+    case 'skip': {
+      const entry = nextState.skippedStages[nextState.skippedStages.length - 1];
+      if (!entry) throw new Error('skip projection requires a skipped stage entry');
+      emit('stage-skipped', entry.stage, { reason: entry.reason, policy: entry.policy, evidence: [...entry.evidence] });
+      break;
+    }
+    case 'block':
+      emit('workflow-blocked', null, {
+        blockerIds: [...nextState.blockers].map((b) => b.id).sort(),
+        blockerTypes: [...nextState.blockers].map((b) => b.type).sort(),
+      });
+      break;
+    case 'unblock':
+      break;
+    case 'interrupt':
+      emit('workflow-interrupted', null, {});
+      break;
+    case 'resume': {
+      const outcome = input.resolutionOutcome ?? (nextState.status === 'BLOCKED' ? 'blocked' : 'ready');
+      emit('workflow-resumed', null, { outcome, staleReason: input.staleReason ?? null });
+      if (outcome === 'blocked') {
+        emit('workflow-blocked', null, {
+          blockerIds: [...nextState.blockers].map((b) => b.id).sort(),
+          blockerTypes: [...nextState.blockers].map((b) => b.type).sort(),
+        });
+      }
+      break;
+    }
+    case 'finalize':
+      emit('workflow-completed', null, {
+        completedStages: nextState.completedStages.map((c) => c.stage),
+        skippedStages: nextState.skippedStages.map((s) => s.stage),
+      });
+      break;
+    default:
+      throw new Error(`Unknown workflow trace op: ${op}`);
+  }
+  return Object.freeze(events);
+}
+
+export const workflowTraceAPI = {
+  projectWorkflowEvents,
+  eventKey,
+  normalizeTrace,
+  assertNoAuthority,
+  validateWorkflowEvent,
+};