showdar-skills 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -4,7 +4,36 @@ 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.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,25 @@
+# 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,64 @@ 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.
+
 ## A typical software workflow
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },

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,54 @@ 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}`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
 export async function validateRepository(packageRoot) {
   const errors = [];
   const warnings = [];
@@ -254,6 +302,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,
+};