harness-everything 0.31.3 → 0.32.0

package/ci/mechanism-2ba-step-type-docs.test.js

@@ -0,0 +1,166 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const registryFile = path.join(ROOT, 'hooks', 'scripts', 'lib', 'step-types.json');
+const routerFile = path.join(ROOT, 'harness-everything', 'scripts', 'kernel-router.js');
+const AUTHORITATIVE_DOC = 'harness-everything/references/router-workflow-plan.md';
+const ALLOWED_LIST_DOCS = [
+  'docs/routing.md',
+  'harness-everything/references/router-workflow-plan.md',
+  'harness-everything/references/triage-and-tiers.md',
+  'docs/workflows/harness-everything.md',
+];
+const START = '<!-- step-types:start -->';
+const END = '<!-- step-types:end -->';
+const FIX_PROMPT = 'Fix this checkout bug and add a regression test.';
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-step-type-docs-'));
+let failed = 0;
+
+process.on('exit', () => fs.rmSync(tempRoot, { recursive: true, force: true }));
+
+console.log('\n[2ba] step-type registry documentation and router drift...');
+
+function check(name, ok, detail) {
+  if (ok) console.log(`✅ ${name}`);
+  else {
+    failed++;
+    console.log(`❌ ${name}`);
+    if (detail) console.log(`   ${detail}`);
+  }
+}
+
+function checkCase(name, run) {
+  try {
+    run();
+    check(name, true);
+  } catch (error) {
+    check(name, false, error && error.message ? error.message : String(error));
+  }
+}
+
+// Independent oracle: renders the registry directly from the JSON file, not through the runtime loader.
+function renderRegistry(entries) {
+  const byId = (left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+  const list = bindings => bindings.map(binding => `\`${binding}\``).join(', ') || 'none';
+  return entries.slice().sort(byId).map(entry =>
+    `- \`${entry.id}\` — required bindings: ${list(entry.requiredBindings)} — forbidden bindings: ${list(entry.forbiddenBindings)}`,
+  );
+}
+
+function markerBlocks(text, label) {
+  const lines = text.split('\n');
+  const blocks = [];
+  let openAt = null;
+  lines.forEach((line, index) => {
+    const marker = line.trim();
+    if (marker === START) {
+      if (openAt !== null) throw new Error(`${label}: nested step-types:start at line ${index + 1}`);
+      openAt = index;
+    } else if (marker === END) {
+      if (openAt === null) throw new Error(`${label}: step-types:end without start at line ${index + 1}`);
+      blocks.push(lines.slice(openAt + 1, index).map(item => item.trim()).filter(Boolean));
+      openAt = null;
+    }
+  });
+  if (openAt !== null) throw new Error(`${label}: step-types:start is never closed`);
+  return blocks;
+}
+
+function routeFixPrompt(runtimeRoot, workspace) {
+  const home = path.join(tempRoot, `home-${Math.random().toString(36).slice(2)}`);
+  fs.mkdirSync(home, { recursive: true });
+  const payload = { session_id: `2ba-${Math.random().toString(36).slice(2)}`, cwd: workspace, prompt: FIX_PROMPT };
+  return spawnSync(process.execPath, [path.join(runtimeRoot, 'harness-everything', 'scripts', 'kernel-router.js')], {
+    cwd: workspace,
+    encoding: 'utf8',
+    input: JSON.stringify(payload),
+    env: {
+      ...process.env,
+      HARNESS_STATE_HOME: path.join(tempRoot, 'state'),
+      HARNESS_WORKSPACE_ROOT: workspace,
+      HOME: home,
+      USERPROFILE: home,
+    },
+  });
+}
+
+const registry = JSON.parse(fs.readFileSync(registryFile, 'utf8'));
+const registryIds = registry.map(entry => entry.id).sort();
+const expectedLines = renderRegistry(registry);
+
+checkCase('2ba. every step-types marker block in the allowed-list docs equals the registry rendering', () => {
+  let total = 0;
+  for (const doc of ALLOWED_LIST_DOCS) {
+    const blocks = markerBlocks(fs.readFileSync(path.join(ROOT, doc), 'utf8'), doc);
+    for (const block of blocks) {
+      total++;
+      if (JSON.stringify(block) !== JSON.stringify(expectedLines)) {
+        throw new Error(`${doc} marker block drifted from the registry:\n${block.join('\n')}\nexpected:\n${expectedLines.join('\n')}`);
+      }
+    }
+  }
+  if (total === 0) throw new Error('no step-types marker block found in any allowed-list doc');
+  const authoritative = markerBlocks(fs.readFileSync(path.join(ROOT, AUTHORITATIVE_DOC), 'utf8'), AUTHORITATIVE_DOC);
+  if (authoritative.length !== 1) throw new Error(`${AUTHORITATIVE_DOC} must carry exactly one step-types marker block; found ${authoritative.length}`);
+});
+
+checkCase('2ba. router lists exactly the registry step-type ids', () => {
+  const routed = routeFixPrompt(ROOT, ROOT);
+  if (routed.status !== 0) throw new Error(`router exited ${routed.status}: ${routed.stderr}`);
+  const match = routed.stdout.match(/Record ordered step types \(([^)]*)\) and their bindings/);
+  if (!match) throw new Error('router did not print the ordered step-type list');
+  const listed = match[1].split(',').map(item => item.trim());
+  if (JSON.stringify(listed) !== JSON.stringify(registryIds)) {
+    throw new Error(`router listed [${listed.join(', ')}]; registry ids are [${registryIds.join(', ')}]`);
+  }
+});
+
+checkCase('2ba. router example plan does not steer step authoring toward behavior-change', () => {
+  const routed = routeFixPrompt(ROOT, ROOT);
+  const recordPlan = routed.stdout.split('\n').find(line => line.includes('Record plan:')) || '';
+  if (!recordPlan) throw new Error('router did not print a Record plan example');
+  if (recordPlan.includes('behavior-change')) throw new Error(`example still hard-codes behavior-change: ${recordPlan}`);
+});
+
+checkCase('2ba. router prints the explicit-choice guidance line exactly once in fresh tier2 output', () => {
+  const guidance = '- Replace <step-type-id> with a registered type you choose explicitly; mixed docs+code work uses separate doc-change and behavior-change steps; keep the verification step.';
+  const routed = routeFixPrompt(ROOT, ROOT);
+  if (routed.status !== 0) throw new Error(`router exited ${routed.status}: ${routed.stderr}`);
+  const matches = routed.stdout.split('\n').filter(line => line.trim() === guidance);
+  if (matches.length !== 1) throw new Error(`expected the guidance line exactly once; found ${matches.length}`);
+});
+
+checkCase('2ba. router record-plan guidance keeps the space after "node" in fresh tier2 output', () => {
+  const routed = routeFixPrompt(ROOT, ROOT);
+  if (routed.status !== 0) throw new Error(`router exited ${routed.status}: ${routed.stderr}`);
+  if (!routed.stdout.includes('   - Record plan: node "')) {
+    throw new Error(`router record-plan line lacks "Record plan: node"; got: ${routed.stdout.split('\n').find(line => line.includes('Record plan')) || '(none)'}`);
+  }
+});
+
+checkCase('2ba. router never crashes or prints a stale step-type list when the registry is missing', () => {
+  const copy = path.join(tempRoot, 'runtime-without-registry');
+  fs.cpSync(ROOT, copy, {
+    recursive: true,
+    filter: source => !/[\\/](node_modules|\.git|benchmarks|plugins)([\\/]|$)/.test(source),
+  });
+  fs.rmSync(path.join(copy, 'hooks', 'scripts', 'lib', 'step-types.json'));
+  const routed = routeFixPrompt(copy, copy);
+  if (routed.status !== 0) throw new Error(`router exited ${routed.status} without the registry: ${routed.stderr}`);
+  if (/Record ordered step types \(/.test(routed.stdout)) throw new Error('router printed a step-type list without a registry');
+  if (!routed.stderr.includes('cannot load step-type registry')) {
+    throw new Error(`router did not surface the missing registry visibly; stderr: ${routed.stderr}`);
+  }
+});
+
+checkCase('2ba. router-workflow-plan documents old-runtime rejection of persisted doc-change plans', () => {
+  const text = fs.readFileSync(path.join(ROOT, AUTHORITATIVE_DOC), 'utf8');
+  for (const required of ['doc-change', 'declared-only', 'planning:steps-invalid']) {
+    if (!text.includes(required)) throw new Error(`${AUTHORITATIVE_DOC} must mention ${required}`);
+  }
+});
+
+process.exitCode = failed ? 1 : 0;

package/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through Harness: classify tier/topolog
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.32.0
 ---
 
 # Harness Everything

package/harness-everything/references/router-workflow-plan.md

@@ -118,6 +118,24 @@ Examples:
 
 There is no universal `TODO → TDD → verification` pipeline.
 
+## Step types
+
+The allowed step types are the entries of `hooks/scripts/lib/step-types.json`. The list below is rendered from that registry and checked against it by `ci/mechanism-2ba-step-type-docs.test.js`; examples elsewhere may name a subset.
+
+<!-- step-types:start -->
+- `behavior-change` — required bindings: `tdd` — forbidden bindings: none
+- `commit` — required bindings: `git-commit` — forbidden bindings: none
+- `doc-change` — required bindings: none — forbidden bindings: none
+- `review` — required bindings: none — forbidden bindings: `tdd`
+- `verification` — required bindings: `verification-loop` — forbidden bindings: none
+<!-- step-types:end -->
+
+`doc-change` is declared-only: a plan author chooses it explicitly, and router classification, keyword routing and System One never infer or insert it. It has no default bindings, and an explicitly declared `tdd` binding stays legal. Mixed documentation and code work is written as ordered `doc-change` and `behavior-change` steps, and one shared verification step may verify both.
+
+Old runtimes reject a persisted non-Fable `doc-change` plan visibly at the controller and Stop boundaries (`planning:steps-invalid`). The old retained router does not show that rejection: it shows no active step. Persisted bytes are not renamed or reset. Inert Fable planning metadata is not rejected by old runtimes, because step bindings are disabled there.
+
+Registry revisions: binding defaults and required/forbidden binding policy are materialized when a plan is recorded and are not reapplied on ordinary load. Existing typed plans must still reference currently registered step types; removing a type can invalidate a plan rather than migrate or waive its stored bindings. A policy fingerprint or migration path is future work and is not implemented today.
+
 ## Binding and disclosure rule
 
 Each ordered requirement or Fable stage may declare `requiredBindings` and `optionalBindings` by stable id and concrete repository-relative path. Only the active requirement or dependency-ready stage exposes its paths. Required bindings must resolve before that step/stage passes; unknown required bindings remain visible and unresolved. Future-step paths and keyword-matched documents are never preloaded.

package/harness-everything/scripts/kernel-router.js

@@ -33,6 +33,14 @@ function issueMemoryCapability(workflow) {
   return token;
 }
 
+function needsStepTypeRegistry(plan) {
+  return Boolean(
+    plan && plan.strategySelection === 'selected' &&
+    ['tier2', 'tier3'].includes(plan.tier) && plan.strategy &&
+    !String(plan.strategy).startsWith('fable-')
+  );
+}
+
 // Host-generated background-task notifications arrive as UserPromptSubmit
 // hook payloads but are not user input (#168). Routing them like prompts
 // replaces the workflow contract mid-turn (e.g. deferred -> a new Tier-2).
@@ -44,11 +52,28 @@ function isHostNotificationPrompt(prompt) {
   return /^<task-notification[\s>][\s\S]*<\/task-notification>\s*$/i.test(text);
 }
 
+function stepTypeIdsFor(hooksRoot) {
+  try {
+    return require(path.join(hooksRoot, 'lib/workflow-obligations')).stepTypeIds();
+  } catch {
+    return null;
+  }
+}
+
 function persistWorkflow(contract, payload, prompt) {
   const plan = contract && contract.workflowPlan;
   if (!payload || !(payload.session_id || payload.sessionId)) return null;
   const { runtime, hooksRoot } = loadRuntime();
   const context = runtime.loadWorkflow(payload);
+  const hasRetainedWorkflow = Boolean(context.workflow && runtime.OPEN_STATES.has(context.workflow.state));
+  const activePlan = hasRetainedWorkflow ? context.workflow.workflowPlan : plan;
+  if (needsStepTypeRegistry(activePlan)) {
+    try { require(path.join(hooksRoot, 'lib/workflow-obligations')).loadStepTypeRegistry(); }
+    catch (error) {
+      if (hasRetainedWorkflow) return { ...context, hooksRoot, retained: true, registryError: error };
+      throw error;
+    }
+  }
   const { writeCurrentSession } = require(path.join(hooksRoot, 'lib/harness-state'));
   writeCurrentSession(context.root, context.sessionId);
   if (isHostNotificationPrompt(prompt)) {
@@ -121,8 +146,8 @@ function activeExecutionFor(persisted, plan) {
     const obligations = require(path.join(persisted.hooksRoot, 'lib/workflow-obligations'));
     const loaded = obligations.loadObligationSet(persisted, plan);
     return { activeStep: loaded.set ? obligations.activeStepSnapshot(loaded.set) : null };
-  } catch (_) {
-    return null;
+  } catch (error) {
+    return { error: error && error.message ? error.message : String(error) };
   }
 }
 
@@ -163,10 +188,15 @@ function run(raw) {
   if (persisted?.retained && persisted.workflow) {
     if (persisted.hostNotification) console.log('\n=> Host notification: routing unchanged; keeping the active execution contract.');
     else console.log('\n=> Retaining unresolved workflow; showing its compact active contract.');
-    const activeExecution = activeExecutionFor(persisted, plan) || {};
+    const activeExecution = persisted.registryError
+      ? { error: persisted.registryError.message || String(persisted.registryError) }
+      : activeExecutionFor(persisted, plan) || {};
     const activeStep = activeExecution.activeStep || null;
     const activeStages = activeExecution.activeStages || [];
     core.printRetainedWorkflow(plan, persisted.workflow, activeStep, activeStages);
+    if (activeExecution.error) {
+      console.log('   - [Workflow Reminder] Active-step context unavailable: ' + activeExecution.error);
+    }
     if (activeStep) {
       const controller = path.join(persisted.hooksRoot, 'workflow-disposition.js');
       console.log('   - Resolve only bindings for this active step, then pass this step with evidence.');
@@ -205,8 +235,10 @@ function run(raw) {
     if (plan.strategySelection === 'selected' && ['tier2', 'tier3'].includes(plan.tier)) {
       console.log('   - Planning contract: ' + path.join(persisted.sessionDir, 'workflow-obligations.json'));
       console.log('   - Requirements first: decompose intent into requirement fragments, then confirm the smallest sufficient workflow.');
-      console.log('   - Record ordered step types (review, behavior-change, verification, commit) and their bindings before execution.');
-      console.log('   - Record plan: node "' + controller + '" plan --session-id "' + persisted.sessionId + '" --requirements-json "[{\\"id\\":\\"req-1\\",\\"stepType\\":\\"behavior-change\\",\\"summary\\":\\"...\\",\\"acceptance\\":\\"...\\"},{\\"id\\":\\"req-verify\\",\\"stepType\\":\\"verification\\",\\"summary\\":\\"...\\",\\"acceptance\\":\\"...\\"}]" --strategy "' + plan.strategy + '" --evidence "<why this workflow fits>"');
+      const stepTypeIds = stepTypeIdsFor(persisted.hooksRoot);
+      console.log('   - Record ordered step types' + (stepTypeIds ? ' (' + stepTypeIds.join(', ') + ')' : '') + ' and their bindings before execution.');
+      console.log('   - Replace <step-type-id> with a registered type you choose explicitly; mixed docs+code work uses separate doc-change and behavior-change steps; keep the verification step.');
+      console.log('   - Record plan: node "' + controller + '" plan --session-id "' + persisted.sessionId + '" --requirements-json "[{\\"id\\":\\"req-1\\",\\"stepType\\":\\"<step-type-id>\\",\\"summary\\":\\"...\\",\\"acceptance\\":\\"...\\"},{\\"id\\":\\"req-verify\\",\\"stepType\\":\\"verification\\",\\"summary\\":\\"...\\",\\"acceptance\\":\\"...\\"}]" --strategy "' + plan.strategy + '" --evidence "<why this workflow fits>"');
     }
     console.log('   - Enter selected workflow after planning: node "' + controller + '" start --session-id "' + persisted.sessionId + '"');
     console.log('   - Escape one declared stage: node "' + controller + '" escape --session-id "' + persisted.sessionId + '" --stage-id "<id>" --reason-code workflow-uncovered-scope --scope "<uncovered scope>" --evidence "<evidence>"');

package/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/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/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.3",
+  "version": "0.32.0",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"