harness-everything 0.31.2 → 0.32.0

package/hooks/scripts/lib/workflow-obligations.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 const { atomicWriteJson, readJson } = require('./fable-contracts');
 const { resolveBinding, PACKAGED_BINDING_PATHS: BINDING_PATHS } = require('./binding-resolver');
@@ -8,13 +9,102 @@ const OBLIGATION_SCHEMA_VERSION = 1;
 const OBLIGATION_FILE = 'workflow-obligations.json';
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const ALLOWED_ESCAPE_REASONS = new Set(['workflow-uncovered-scope', 'host-capability-unavailable']);
-const STEP_TYPES = new Set(['review', 'behavior-change', 'verification', 'commit']);
-const REQUIRED_BINDINGS_BY_STEP = {
-  review: [],
-  'behavior-change': ['tdd'],
-  verification: ['verification-loop'],
-  commit: ['git-commit'],
-};
+const STEP_TYPE_REGISTRY_FILE = path.join(__dirname, 'step-types.json');
+
+function validateStepTypeRegistry(registry) {
+  const errors = [];
+  if (!Array.isArray(registry) || registry.length === 0) {
+    throw new Error('invalid step-type registry: expected a non-empty array');
+  }
+  const idCounts = new Map();
+  const bindingFields = ['requiredBindings', 'optionalBindings', 'forbiddenBindings'];
+  for (const entry of registry) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      errors.push('entry must be an object');
+      continue;
+    }
+    const id = typeof entry.id === 'string' ? entry.id : '';
+    const validId = SAFE_ID.test(id) && id === id.trim();
+    const label = validId ? `step type ${id}` : 'step type with invalid id';
+    if (!validId) errors.push(`${label} must declare a stable id`);
+    else idCounts.set(id, (idCounts.get(id) || 0) + 1);
+    if (typeof entry.evidenceHint !== 'string' || !entry.evidenceHint.trim()) {
+      errors.push(`${label} evidenceHint must be a non-empty string`);
+    }
+    const valuesByField = new Map();
+    for (const field of bindingFields) {
+      if (!Array.isArray(entry[field])) {
+        errors.push(`${label} ${field} must be an array`);
+        valuesByField.set(field, []);
+        continue;
+      }
+      const values = [];
+      for (const binding of entry[field]) {
+        if (typeof binding !== 'string' || !SAFE_ID.test(binding) || binding !== binding.trim()) {
+          errors.push(`${label} ${field} entries must be stable binding ids`);
+          continue;
+        }
+        values.push(binding);
+      }
+      const unique = [...new Set(values)].sort();
+      if (unique.length !== values.length) errors.push(`${label} ${field} contains duplicate binding ids`);
+      valuesByField.set(field, unique);
+    }
+    for (const [left, right] of [
+      ['requiredBindings', 'optionalBindings'],
+      ['requiredBindings', 'forbiddenBindings'],
+      ['optionalBindings', 'forbiddenBindings'],
+    ]) {
+      const rightValues = new Set(valuesByField.get(right) || []);
+      for (const binding of valuesByField.get(left) || []) {
+        if (rightValues.has(binding)) errors.push(`${label} has conflicting ${left} and ${right} default for ${binding}`);
+      }
+    }
+  }
+  for (const id of [...idCounts.keys()].sort()) {
+    if (idCounts.get(id) > 1) errors.push(`duplicate step type id ${id}`);
+  }
+  if (errors.length) throw new Error('invalid step-type registry: ' + [...new Set(errors)].sort().join('; '));
+  return registry.map(entry => ({
+    id: entry.id,
+    requiredBindings: [...entry.requiredBindings],
+    optionalBindings: [...entry.optionalBindings],
+    forbiddenBindings: [...entry.forbiddenBindings],
+    evidenceHint: entry.evidenceHint.trim(),
+  })).sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+}
+
+const STEP_TYPE_REGISTRY_UNAVAILABLE = 'STEP_TYPE_REGISTRY_UNAVAILABLE';
+
+function readStepTypeRegistry(registryFile = STEP_TYPE_REGISTRY_FILE) {
+  const resolvedRegistryFile = path.resolve(registryFile);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(resolvedRegistryFile, 'utf8'));
+    return validateStepTypeRegistry(parsed);
+  } catch (error) {
+    const unavailable = new Error(
+      `cannot load step-type registry ${resolvedRegistryFile}: ${error.message}. ` +
+      `Repair action: reinstall or update the Harness plugin so this file is restored; in a Harness source checkout, restore it and run npm run plugin:sync.`,
+    );
+    unavailable.code = STEP_TYPE_REGISTRY_UNAVAILABLE;
+    throw unavailable;
+  }
+}
+
+// Loaded on first typed use only, so registry-independent planning and execution never read it.
+let stepTypeRegistry = null;
+function loadStepTypeRegistry() {
+  if (!stepTypeRegistry) stepTypeRegistry = readStepTypeRegistry();
+  return stepTypeRegistry;
+}
+
+function stepTypeIds() {
+  return loadStepTypeRegistry().map(entry => entry.id).sort();
+}
+
+function stepTypeIndex() {
+  return new Map(loadStepTypeRegistry().map(entry => [entry.id, entry]));
+}
 
 function obligationPath(sessionDir) {
   return path.join(sessionDir, OBLIGATION_FILE);
@@ -125,6 +215,14 @@ function initializePlanningContract(context, plan) {
   return set;
 }
 
+function typedStepType(rawStepType) {
+  const registered = stepTypeIndex();
+  if (!registered.has(rawStepType)) {
+    throw new Error(`unsupported requirement stepType: ${rawStepType}; registered step types: ${stepTypeIds().join(', ')}`);
+  }
+  return registered.get(rawStepType);
+}
+
 function parseRequirements(requirementsJson, workspaceRoot) {
   let parsed;
   try { parsed = JSON.parse(String(requirementsJson || '')); }
@@ -145,7 +243,7 @@ function parseRequirements(requirementsJson, workspaceRoot) {
       ? [...new Set(item.suggestedSkills.filter(value => typeof value === 'string' && value.trim()).map(value => value.trim()))]
       : [];
     const rawStepType = item.stepType === undefined ? '' : String(item.stepType).trim();
-    if (rawStepType && !STEP_TYPES.has(rawStepType)) throw new Error(`unsupported requirement stepType: ${rawStepType}`);
+    const stepType = rawStepType ? typedStepType(rawStepType) : null;
     for (const field of ['requiredBindings', 'optionalBindings']) {
       if (Object.prototype.hasOwnProperty.call(item, field) && !Array.isArray(item[field])) {
         throw new Error(`${id}.${field} must be an array`);
@@ -155,17 +253,18 @@ function parseRequirements(requirementsJson, workspaceRoot) {
     if (!rawStepType) return requirement;
 
     const requiredBindings = normalizeBindingDeclarations([
-      ...(REQUIRED_BINDINGS_BY_STEP[rawStepType] || []),
+      ...(stepType.requiredBindings || []),
       ...(item.requiredBindings || []),
     ]);
     const requiredIds = new Set(requiredBindings.map(binding => binding.id));
     const optionalBindings = normalizeBindingDeclarations([
+      ...(stepType.optionalBindings || []),
       ...(item.optionalBindings || []),
       ...suggestedSkills,
     ]).filter(binding => !requiredIds.has(binding.id));
-    if (rawStepType === 'review' && [...requiredBindings, ...optionalBindings].some(binding => binding.id === 'tdd')) {
-      throw new Error('review steps cannot bind tdd');
-    }
+    const forbiddenBinding = [...requiredBindings, ...optionalBindings]
+      .find(binding => stepType.forbiddenBindings.includes(binding.id));
+    if (forbiddenBinding) throw new Error(`${rawStepType} steps cannot bind ${forbiddenBinding.id}`);
     requirement.stepType = rawStepType;
     requirement.status = 'pending';
     requirement.evidence = null;
@@ -268,7 +367,7 @@ function recordPlanning(context, requirementsJson, selectedPlan, requestedStrate
   }
   const isFable = String(selectedPlan.strategy || '').startsWith('fable-');
   if (!isFable && !hasTypedSteps) {
-    throw new Error('selected single-agent workflows require ordered stepType values: review, behavior-change, verification, or commit');
+    throw new Error(`selected single-agent workflows require ordered stepType values: ${stepTypeIds().join(', ')}`);
   }
   if (!isFable && !requirements.some(item => item.stepType === 'verification')) {
     throw new Error('step-bound workflows require an explicit verification step');
@@ -360,7 +459,8 @@ function validateObligationSet(context, set, plan = context.workflow?.pendingPla
     if (!['pending', 'pass', 'escaped', 'blocked'].includes(obligation.status)) return 'obligation-status-invalid';
   }
   if (set.stepBindingsEnabled === true) {
-    if (set.requirements.some(item => !item || !STEP_TYPES.has(item.stepType) ||
+    const registered = stepTypeIndex();
+    if (set.requirements.some(item => !item || !registered.has(item.stepType) ||
         !['pending', 'pass', 'blocked'].includes(item.status) || !Array.isArray(item.requiredBindings) ||
         !Array.isArray(item.optionalBindings))) return 'steps-invalid';
     for (const step of set.requirements) {
@@ -585,6 +685,9 @@ function unresolvedObligations(context) {
 module.exports = {
   OBLIGATION_FILE,
   ALLOWED_ESCAPE_REASONS,
+  loadStepTypeRegistry,
+  stepTypeIds,
+  validateStepTypeRegistry,
   obligationPath,
   needsPlanningContract,
   needsGenericExecutionObligations,

package/hooks/scripts/workflow-disposition.js

@@ -7,15 +7,20 @@ const { loadWorkflow, saveWorkflow, matchingRun, OPEN_STATES, WORKFLOW_CONTROLLE
 const { getWorkspaceRoot, readCurrentSession } = require('./lib/harness-state');
 const { atomicWriteJson, readJson } = require('./lib/fable-contracts');
 const { resolveBinding } = require('./lib/binding-resolver');
-const {
-  planningUnresolved,
-  recordPlanning,
-  materializeExecutionObligations,
-  updateObligation,
-  updateBinding,
-  updateStep,
-  activeStepSnapshot,
-} = require('./lib/workflow-obligations');
+
+let obligationApi;
+function workflowObligations() {
+  if (!obligationApi) obligationApi = require('./lib/workflow-obligations');
+  return obligationApi;
+}
+
+const planningUnresolved = (...args) => workflowObligations().planningUnresolved(...args);
+const recordPlanning = (...args) => workflowObligations().recordPlanning(...args);
+const materializeExecutionObligations = (...args) => workflowObligations().materializeExecutionObligations(...args);
+const updateObligation = (...args) => workflowObligations().updateObligation(...args);
+const updateBinding = (...args) => workflowObligations().updateBinding(...args);
+const updateStep = (...args) => workflowObligations().updateStep(...args);
+const activeStepSnapshot = (...args) => workflowObligations().activeStepSnapshot(...args);
 
 const ALLOWED_ESCAPE_REASONS = new Set(['workflow-uncovered-scope', 'host-capability-unavailable']);
 
@@ -149,6 +154,8 @@ function activatePlan(workflow, plan) {
 }
 
 function main() {
+  // The step-type registry loads lazily through the wrappers above, only for commands that
+  // consume typed obligations; the top-level handler turns a load failure into one semantic line.
   if (process.argv[2] === '--help' || process.argv[2] === '-h') {
     process.stdout.write(usage() + '\n');
     return;

package/hooks/scripts/workflow-stop-gate.js

@@ -3,35 +3,58 @@
 const path = require('path');
 const { readJson } = require('./lib/fable-contracts');
 const { loadWorkflow, saveWorkflow, matchingRun, unresolvedStages, readHookInput } = require('./lib/workflow-runtime');
-const { planningUnresolved, unresolvedObligations } = require('./lib/workflow-obligations');
+
+const REGISTRY_UNAVAILABLE = 'step-type-registry-unavailable';
+const STEP_TYPE_REGISTRY_UNAVAILABLE = 'STEP_TYPE_REGISTRY_UNAVAILABLE';
 
 function warn(message) { console.error('[Workflow Reminder] ' + message); }
 
 function decide(payload) {
   if (!payload) return;
   try {
+    const { planningUnresolved, unresolvedObligations } = require('./lib/workflow-obligations');
     const context = loadWorkflow(payload);
     const { workflow, sessionDir } = context;
     if (!workflow || workflow.state === 'deferred') return;
     const handoff = readJson(path.join(sessionDir, 'handoff-state.json'));
-    let unresolved = planningUnresolved(context);
+    const unresolved = [];
+    const diagnostics = [];
+    let requiredFault = false;
+
+    // Only a validation that actually reads the registry can fail here. It records the
+    // semantic diagnostic and the unresolved token itself; other checks keep running.
+    const required = check => {
+      try {
+        unresolved.push(...check());
+      } catch (error) {
+        if (error.code !== STEP_TYPE_REGISTRY_UNAVAILABLE) throw error;
+        diagnostics.push(error.message);
+        unresolved.push(REGISTRY_UNAVAILABLE);
+        requiredFault = true;
+      }
+    };
 
+    required(() => planningUnresolved(context));
     if (String(workflow.strategy || '').startsWith('fable-')) {
       const match = matchingRun(context);
       unresolved.push(...(match ? unresolvedStages(match, workflow, handoff?.lastEditAt || 0) : ['correlated-run-missing']));
     } else {
-      unresolved.push(...unresolvedObligations(context));
+      required(() => unresolvedObligations(context));
       const lastEdit = Math.max(workflow.lastMutationAt || 0, handoff?.lastEditAt || 0);
       if (lastEdit && (handoff?.lastVerifyAt || 0) < lastEdit) unresolved.push('verification-after-edit-missing');
     }
 
-    unresolved = [...new Set(unresolved)];
+    const pending = [...new Set(unresolved)];
     const wasBlocked = workflow.state === 'blocked';
     if (wasBlocked) warn('Workflow is marked BLOCKED; report or revisit the recorded blocker, but Harness will not trap the session.');
-    if (unresolved.length) {
-      workflow.unresolved = unresolved;
-      saveWorkflow(context);
-      warn('Unresolved workflow evidence: ' + unresolved.join(', ') + '. Resolve/verify before claiming completion.');
+    [...new Set(diagnostics)].forEach(message => warn(message));
+    if (pending.length) {
+      // A failed required validation leaves the workflow file as recorded; it is never marked satisfied.
+      if (!requiredFault) {
+        workflow.unresolved = pending;
+        saveWorkflow(context);
+      }
+      warn('Unresolved workflow evidence: ' + pending.join(', ') + '. Resolve/verify before claiming completion.');
       return;
     }
     if (wasBlocked) return;

package/opencode-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-enforcement",
   "description": "Repository inventory for the opencode enforcement plugin and its standalone helper",
-  "version": "0.31.2",
+  "version": "0.32.0",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.31.2",
+  "version": "0.32.0",
   "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
   "main": "harness-everything/scripts/bootstrap.js",
   "bin": {
@@ -63,7 +63,7 @@
     "waza:check": "node scripts/waza-harness-check.js",
     "test:waza:compat": "node ci/mechanism-2aj-waza-reference-adapter.test.js",
     "codex:hooks": "node scripts/codex-hooks-compat.js",
-    "test:codex:hooks-compat": "node ci/mechanism-2al-codex-hooks-compat.test.js"
+    "test:codex:hooks-compat": "node ci/mechanism-2al-codex-hooks-compat.test.js && node ci/mechanism-2au-codex-runtime-safety.test.js"
   },
   "engines": {
     "node": ">=22"

package/plugins/harness-everything/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.31.2",
+  "version": "0.32.0",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/hooks/scripts/codex-user-prompt.js

@@ -24,8 +24,11 @@ function finish() {
   clearTimeout(timer);
   if (!ROUTER) process.exit(0);
   const result = spawnSync(process.execPath, [ROUTER], { input, encoding: 'utf8', env: process.env, timeout: 25000 });
-  if (result.stderr) process.stderr.write(result.stderr);
-  const context = String(result.stdout || '').trim();
+  const stderr = String(result.stderr || '');
+  if (stderr) process.stderr.write(stderr);
+  const registryDiagnostics = stderr.split(/\r?\n/)
+    .filter(line => line.includes('cannot load step-type registry') && /(repair|restore|plugin:sync)/i.test(line));
+  const context = [String(result.stdout || '').trim(), ...registryDiagnostics].filter(Boolean).join('\n').trim();
   if (context) {
     process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: context } }));
   }

package/plugins/harness-everything/hooks/scripts/lib/step-types.json

@@ -0,0 +1,37 @@
+[
+  {
+    "id": "behavior-change",
+    "requiredBindings": ["tdd"],
+    "optionalBindings": [],
+    "forbiddenBindings": [],
+    "evidenceHint": "Evidence should show the requested behavior changed."
+  },
+  {
+    "id": "commit",
+    "requiredBindings": ["git-commit"],
+    "optionalBindings": [],
+    "forbiddenBindings": [],
+    "evidenceHint": "Evidence should identify the authorized commit."
+  },
+  {
+    "id": "doc-change",
+    "requiredBindings": [],
+    "optionalBindings": [],
+    "forbiddenBindings": [],
+    "evidenceHint": "Evidence should show the requested document update."
+  },
+  {
+    "id": "review",
+    "requiredBindings": [],
+    "optionalBindings": [],
+    "forbiddenBindings": ["tdd"],
+    "evidenceHint": "Evidence should identify the reviewed scope and findings."
+  },
+  {
+    "id": "verification",
+    "requiredBindings": ["verification-loop"],
+    "optionalBindings": [],
+    "forbiddenBindings": [],
+    "evidenceHint": "Evidence should record objective checks appropriate to the change."
+  }
+]

package/plugins/harness-everything/hooks/scripts/lib/workflow-obligations.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 const { atomicWriteJson, readJson } = require('./fable-contracts');
 const { resolveBinding, PACKAGED_BINDING_PATHS: BINDING_PATHS } = require('./binding-resolver');
@@ -8,13 +9,102 @@ const OBLIGATION_SCHEMA_VERSION = 1;
 const OBLIGATION_FILE = 'workflow-obligations.json';
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const ALLOWED_ESCAPE_REASONS = new Set(['workflow-uncovered-scope', 'host-capability-unavailable']);
-const STEP_TYPES = new Set(['review', 'behavior-change', 'verification', 'commit']);
-const REQUIRED_BINDINGS_BY_STEP = {
-  review: [],
-  'behavior-change': ['tdd'],
-  verification: ['verification-loop'],
-  commit: ['git-commit'],
-};
+const STEP_TYPE_REGISTRY_FILE = path.join(__dirname, 'step-types.json');
+
+function validateStepTypeRegistry(registry) {
+  const errors = [];
+  if (!Array.isArray(registry) || registry.length === 0) {
+    throw new Error('invalid step-type registry: expected a non-empty array');
+  }
+  const idCounts = new Map();
+  const bindingFields = ['requiredBindings', 'optionalBindings', 'forbiddenBindings'];
+  for (const entry of registry) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      errors.push('entry must be an object');
+      continue;
+    }
+    const id = typeof entry.id === 'string' ? entry.id : '';
+    const validId = SAFE_ID.test(id) && id === id.trim();
+    const label = validId ? `step type ${id}` : 'step type with invalid id';
+    if (!validId) errors.push(`${label} must declare a stable id`);
+    else idCounts.set(id, (idCounts.get(id) || 0) + 1);
+    if (typeof entry.evidenceHint !== 'string' || !entry.evidenceHint.trim()) {
+      errors.push(`${label} evidenceHint must be a non-empty string`);
+    }
+    const valuesByField = new Map();
+    for (const field of bindingFields) {
+      if (!Array.isArray(entry[field])) {
+        errors.push(`${label} ${field} must be an array`);
+        valuesByField.set(field, []);
+        continue;
+      }
+      const values = [];
+      for (const binding of entry[field]) {
+        if (typeof binding !== 'string' || !SAFE_ID.test(binding) || binding !== binding.trim()) {
+          errors.push(`${label} ${field} entries must be stable binding ids`);
+          continue;
+        }
+        values.push(binding);
+      }
+      const unique = [...new Set(values)].sort();
+      if (unique.length !== values.length) errors.push(`${label} ${field} contains duplicate binding ids`);
+      valuesByField.set(field, unique);
+    }
+    for (const [left, right] of [
+      ['requiredBindings', 'optionalBindings'],
+      ['requiredBindings', 'forbiddenBindings'],
+      ['optionalBindings', 'forbiddenBindings'],
+    ]) {
+      const rightValues = new Set(valuesByField.get(right) || []);
+      for (const binding of valuesByField.get(left) || []) {
+        if (rightValues.has(binding)) errors.push(`${label} has conflicting ${left} and ${right} default for ${binding}`);
+      }
+    }
+  }
+  for (const id of [...idCounts.keys()].sort()) {
+    if (idCounts.get(id) > 1) errors.push(`duplicate step type id ${id}`);
+  }
+  if (errors.length) throw new Error('invalid step-type registry: ' + [...new Set(errors)].sort().join('; '));
+  return registry.map(entry => ({
+    id: entry.id,
+    requiredBindings: [...entry.requiredBindings],
+    optionalBindings: [...entry.optionalBindings],
+    forbiddenBindings: [...entry.forbiddenBindings],
+    evidenceHint: entry.evidenceHint.trim(),
+  })).sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+}
+
+const STEP_TYPE_REGISTRY_UNAVAILABLE = 'STEP_TYPE_REGISTRY_UNAVAILABLE';
+
+function readStepTypeRegistry(registryFile = STEP_TYPE_REGISTRY_FILE) {
+  const resolvedRegistryFile = path.resolve(registryFile);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(resolvedRegistryFile, 'utf8'));
+    return validateStepTypeRegistry(parsed);
+  } catch (error) {
+    const unavailable = new Error(
+      `cannot load step-type registry ${resolvedRegistryFile}: ${error.message}. ` +
+      `Repair action: reinstall or update the Harness plugin so this file is restored; in a Harness source checkout, restore it and run npm run plugin:sync.`,
+    );
+    unavailable.code = STEP_TYPE_REGISTRY_UNAVAILABLE;
+    throw unavailable;
+  }
+}
+
+// Loaded on first typed use only, so registry-independent planning and execution never read it.
+let stepTypeRegistry = null;
+function loadStepTypeRegistry() {
+  if (!stepTypeRegistry) stepTypeRegistry = readStepTypeRegistry();
+  return stepTypeRegistry;
+}
+
+function stepTypeIds() {
+  return loadStepTypeRegistry().map(entry => entry.id).sort();
+}
+
+function stepTypeIndex() {
+  return new Map(loadStepTypeRegistry().map(entry => [entry.id, entry]));
+}
 
 function obligationPath(sessionDir) {
   return path.join(sessionDir, OBLIGATION_FILE);
@@ -125,6 +215,14 @@ function initializePlanningContract(context, plan) {
   return set;
 }
 
+function typedStepType(rawStepType) {
+  const registered = stepTypeIndex();
+  if (!registered.has(rawStepType)) {
+    throw new Error(`unsupported requirement stepType: ${rawStepType}; registered step types: ${stepTypeIds().join(', ')}`);
+  }
+  return registered.get(rawStepType);
+}
+
 function parseRequirements(requirementsJson, workspaceRoot) {
   let parsed;
   try { parsed = JSON.parse(String(requirementsJson || '')); }
@@ -145,7 +243,7 @@ function parseRequirements(requirementsJson, workspaceRoot) {
       ? [...new Set(item.suggestedSkills.filter(value => typeof value === 'string' && value.trim()).map(value => value.trim()))]
       : [];
     const rawStepType = item.stepType === undefined ? '' : String(item.stepType).trim();
-    if (rawStepType && !STEP_TYPES.has(rawStepType)) throw new Error(`unsupported requirement stepType: ${rawStepType}`);
+    const stepType = rawStepType ? typedStepType(rawStepType) : null;
     for (const field of ['requiredBindings', 'optionalBindings']) {
       if (Object.prototype.hasOwnProperty.call(item, field) && !Array.isArray(item[field])) {
         throw new Error(`${id}.${field} must be an array`);
@@ -155,17 +253,18 @@ function parseRequirements(requirementsJson, workspaceRoot) {
     if (!rawStepType) return requirement;
 
     const requiredBindings = normalizeBindingDeclarations([
-      ...(REQUIRED_BINDINGS_BY_STEP[rawStepType] || []),
+      ...(stepType.requiredBindings || []),
       ...(item.requiredBindings || []),
     ]);
     const requiredIds = new Set(requiredBindings.map(binding => binding.id));
     const optionalBindings = normalizeBindingDeclarations([
+      ...(stepType.optionalBindings || []),
       ...(item.optionalBindings || []),
       ...suggestedSkills,
     ]).filter(binding => !requiredIds.has(binding.id));
-    if (rawStepType === 'review' && [...requiredBindings, ...optionalBindings].some(binding => binding.id === 'tdd')) {
-      throw new Error('review steps cannot bind tdd');
-    }
+    const forbiddenBinding = [...requiredBindings, ...optionalBindings]
+      .find(binding => stepType.forbiddenBindings.includes(binding.id));
+    if (forbiddenBinding) throw new Error(`${rawStepType} steps cannot bind ${forbiddenBinding.id}`);
     requirement.stepType = rawStepType;
     requirement.status = 'pending';
     requirement.evidence = null;
@@ -268,7 +367,7 @@ function recordPlanning(context, requirementsJson, selectedPlan, requestedStrate
   }
   const isFable = String(selectedPlan.strategy || '').startsWith('fable-');
   if (!isFable && !hasTypedSteps) {
-    throw new Error('selected single-agent workflows require ordered stepType values: review, behavior-change, verification, or commit');
+    throw new Error(`selected single-agent workflows require ordered stepType values: ${stepTypeIds().join(', ')}`);
   }
   if (!isFable && !requirements.some(item => item.stepType === 'verification')) {
     throw new Error('step-bound workflows require an explicit verification step');
@@ -360,7 +459,8 @@ function validateObligationSet(context, set, plan = context.workflow?.pendingPla
     if (!['pending', 'pass', 'escaped', 'blocked'].includes(obligation.status)) return 'obligation-status-invalid';
   }
   if (set.stepBindingsEnabled === true) {
-    if (set.requirements.some(item => !item || !STEP_TYPES.has(item.stepType) ||
+    const registered = stepTypeIndex();
+    if (set.requirements.some(item => !item || !registered.has(item.stepType) ||
         !['pending', 'pass', 'blocked'].includes(item.status) || !Array.isArray(item.requiredBindings) ||
         !Array.isArray(item.optionalBindings))) return 'steps-invalid';
     for (const step of set.requirements) {
@@ -585,6 +685,9 @@ function unresolvedObligations(context) {
 module.exports = {
   OBLIGATION_FILE,
   ALLOWED_ESCAPE_REASONS,
+  loadStepTypeRegistry,
+  stepTypeIds,
+  validateStepTypeRegistry,
   obligationPath,
   needsPlanningContract,
   needsGenericExecutionObligations,

package/plugins/harness-everything/hooks/scripts/workflow-disposition.js

@@ -7,15 +7,20 @@ const { loadWorkflow, saveWorkflow, matchingRun, OPEN_STATES, WORKFLOW_CONTROLLE
 const { getWorkspaceRoot, readCurrentSession } = require('./lib/harness-state');
 const { atomicWriteJson, readJson } = require('./lib/fable-contracts');
 const { resolveBinding } = require('./lib/binding-resolver');
-const {
-  planningUnresolved,
-  recordPlanning,
-  materializeExecutionObligations,
-  updateObligation,
-  updateBinding,
-  updateStep,
-  activeStepSnapshot,
-} = require('./lib/workflow-obligations');
+
+let obligationApi;
+function workflowObligations() {
+  if (!obligationApi) obligationApi = require('./lib/workflow-obligations');
+  return obligationApi;
+}
+
+const planningUnresolved = (...args) => workflowObligations().planningUnresolved(...args);
+const recordPlanning = (...args) => workflowObligations().recordPlanning(...args);
+const materializeExecutionObligations = (...args) => workflowObligations().materializeExecutionObligations(...args);
+const updateObligation = (...args) => workflowObligations().updateObligation(...args);
+const updateBinding = (...args) => workflowObligations().updateBinding(...args);
+const updateStep = (...args) => workflowObligations().updateStep(...args);
+const activeStepSnapshot = (...args) => workflowObligations().activeStepSnapshot(...args);
 
 const ALLOWED_ESCAPE_REASONS = new Set(['workflow-uncovered-scope', 'host-capability-unavailable']);
 
@@ -149,6 +154,8 @@ function activatePlan(workflow, plan) {
 }
 
 function main() {
+  // The step-type registry loads lazily through the wrappers above, only for commands that
+  // consume typed obligations; the top-level handler turns a load failure into one semantic line.
   if (process.argv[2] === '--help' || process.argv[2] === '-h') {
     process.stdout.write(usage() + '\n');
     return;