harness-everything 0.30.10 → 0.31.0

package/plugins/harness-everything/hooks/scripts/contract-test.js

@@ -39,16 +39,26 @@ function resultState(payload) {
   return { failed, exitCode, evidence };
 }
 
+function unresolvedBindings(contract) {
+  const bindings = [...(contract.requiredBindings || []), ...(contract.optionalBindings || [])];
+  return bindings.filter(binding => binding.required !== false
+    ? binding.status !== 'loaded'
+    : !['loaded', 'not-needed'].includes(binding.status));
+}
+
 function updateRunContract(entry, payload, command, sessionId) {
   const { failed, exitCode, evidence } = resultState(payload);
+  const unresolved = unresolvedBindings(entry.contract);
+  const status = failed ? 'fail' : unresolved.length ? 'binding-unresolved' : 'pass';
   const observedAt = new Date().toISOString();
   const contract = {
     ...entry.contract,
     workerId: entry.contract.workerId || getWorkerId(payload),
-    status: failed ? 'fail' : 'pass',
+    status,
     lastObservedCommand: command,
     lastObservedExitCode: exitCode ?? null,
     evidence,
+    unresolvedBindings: unresolved.map(binding => binding.id),
     verifiedAt: observedAt,
     updatedAt: observedAt,
   };
@@ -63,7 +73,9 @@ function updateRunContract(entry, payload, command, sessionId) {
     sessionId: sessionId || contract.sessionId || null,
     workerId: contract.workerId || null,
     checkCommand: command,
-    status: failed ? 'fail' : 'pass',
+    status,
+    checkStatus: failed ? 'fail' : 'pass',
+    unresolvedBindings: unresolved.map(binding => binding.id),
     exitCode: exitCode ?? null,
     evidence,
     observedAt,
@@ -72,6 +84,15 @@ function updateRunContract(entry, payload, command, sessionId) {
   return contract;
 }
 
+function activeFableStages(runRoot) {
+  for (const relative of ['../../fable-mode/scripts/workflow-plan-consumer.js', '../../skills/fable-mode/scripts/workflow-plan-consumer.js']) {
+    const file = path.resolve(__dirname, relative);
+    if (!fs.existsSync(file)) continue;
+    try { return require(file).activeStageBindings(runRoot); } catch (_) { return []; }
+  }
+  return [];
+}
+
 function resolveLegacyContract(stateRoot, command, payload) {
   const contractsDir = path.join(stateRoot, 'contracts');
   let files = [];
@@ -110,7 +131,7 @@ process.stdin.on('end', () => {
     const workflowContext = loadWorkflow(payload);
     const activeRun = workflowContext.workflow?.workflowId ? matchingRun(workflowContext) : null;
     const runMatches = listRunContracts(stateRoot).filter(({ contract }) =>
-      (contract.workflowId ? ['pending', 'planned', 'running', 'fail', 'pass'] : ['pending', 'planned', 'running']).includes(contract.status) && commandMatches(contract, command) &&
+      (contract.workflowId ? ['pending', 'planned', 'running', 'fail', 'pass', 'binding-unresolved'] : ['pending', 'planned', 'running', 'fail', 'binding-unresolved']).includes(contract.status) && commandMatches(contract, command) &&
       (!workflowContext.workflow?.workflowId || (activeRun && contract.runId === activeRun.run.runId && contract.sessionId === sessionId))
     );
 
@@ -163,6 +184,11 @@ process.stdin.on('end', () => {
         }
       }
       console.log(`[Contract Test] ${contract.planId}/${contract.runId}/${contract.stageId}: ${contract.status.toUpperCase()} ${contract.checkCommand}`);
+      if (contract.status === 'binding-unresolved') {
+        console.error(`Resolve declared stage bindings before this stage can pass: ${contract.unresolvedBindings.join(', ')}`);
+      }
+      const activeStages = activeFableStages(entry.runRoot);
+      if (activeStages.length) console.log('[Contract Test] Active stage bindings: ' + JSON.stringify(activeStages));
       if (contract.status === 'fail') {
         console.error(`Evidence: ${contract.evidence || '(no output captured)'}`);
         console.error(`Review this failed stage before relying on its output. Artifact: ${contract.outputPath || '(no path recorded)'}`);

package/plugins/harness-everything/hooks/scripts/lib/binding-resolver.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// Resolves a declared step/stage binding to a real, readable file. A binding
+// path is availability evidence only after it resolves under the workspace or
+// an installed Harness skill root; path syntax alone proves nothing.
+const fs = require('fs');
+const path = require('path');
+
+function loadGeneratedSkills() {
+  const file = path.resolve(__dirname, '..', '..', '..', 'scripts', 'lib', 'generated-skills.js');
+  return fs.existsSync(file) ? require(file) : null;
+}
+
+// Source checkout and Claude plugin keep skills at the package root; the
+// Codex plugin keeps them under skills/. Host-provided plugin roots win.
+function packageRoots() {
+  const packageRoot = path.resolve(__dirname, '..', '..', '..');
+  const roots = [];
+  for (const root of [process.env.CLAUDE_PLUGIN_ROOT, process.env.PLUGIN_ROOT, packageRoot]) {
+    if (!root) continue;
+    roots.push(path.resolve(root), path.resolve(root, 'skills'));
+  }
+  return [...new Set(roots)];
+}
+
+function readableFile(file) {
+  try {
+    if (!fs.statSync(file).isFile()) return false;
+    fs.accessSync(file, fs.constants.R_OK);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// Registered Harness bindings and the path each one loads.
+const PACKAGED_BINDING_PATHS = {
+  tdd: 'tdd/SKILL.md',
+  'verification-loop': 'verification-loop/SKILL.md',
+  'git-commit': 'git-commit/SKILL.md',
+  'security-review': 'security-review/SKILL.md',
+  'review-guidance': 'harness-everything/references/triage-and-tiers.md',
+};
+const SKILL_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// Only a recognized Harness binding may search installation roots: a
+// registered id at its registered path, or a skill id naming its own
+// `<id>/SKILL.md`. Any other path is a workspace reference and must never
+// resolve to an unrelated file that happens to exist in the Harness package.
+function isPackagedBinding(binding) {
+  if (!binding.path) return false;
+  if (PACKAGED_BINDING_PATHS[binding.id]) return PACKAGED_BINDING_PATHS[binding.id] === binding.path;
+  return SKILL_ID.test(binding.id || '') && binding.path === `${binding.id}/SKILL.md`;
+}
+
+// Returns { availability, file }: `available` with an absolute readable file,
+// `missing` when a declared path resolves nowhere, or `unknown` when neither a
+// path nor a registered generated skill names a location.
+function resolveBinding(binding, workspaceRoot) {
+  const roots = isPackagedBinding(binding) ? [...packageRoots(), workspaceRoot] : [workspaceRoot];
+  if (binding.path) {
+    for (const root of roots.filter(Boolean)) {
+      const file = path.resolve(root, binding.path);
+      if (readableFile(file)) return { availability: 'available', file };
+    }
+    return { availability: 'missing', file: null };
+  }
+  const generated = loadGeneratedSkills()?.findGeneratedSkill(binding.id, workspaceRoot);
+  if (generated) {
+    const file = path.join(generated.dirPath, 'SKILL.md');
+    return readableFile(file) ? { availability: 'available', file } : { availability: 'missing', file: null };
+  }
+  return { availability: 'unknown', file: null };
+}
+
+module.exports = { resolveBinding, packageRoots, isPackagedBinding, PACKAGED_BINDING_PATHS };

package/plugins/harness-everything/hooks/scripts/lib/fable-contracts.js

@@ -102,7 +102,7 @@ function stagesForChangedPath(filePath, contractEntries) {
 
 function getActiveRunContracts(stateRoot, sessionId) {
   return listRunContracts(stateRoot).filter(({ contract }) => {
-    if (!['pending', 'planned', 'running'].includes(contract.status)) return false;
+    if (!['pending', 'planned', 'running', 'fail', 'binding-unresolved'].includes(contract.status)) return false;
     return !sessionId || !contract.sessionId || contract.sessionId === sessionId;
   });
 }

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

@@ -2,11 +2,19 @@
 
 const path = require('path');
 const { atomicWriteJson, readJson } = require('./fable-contracts');
+const { resolveBinding, PACKAGED_BINDING_PATHS: BINDING_PATHS } = require('./binding-resolver');
 
 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'],
+};
 
 function obligationPath(sessionDir) {
   return path.join(sessionDir, OBLIGATION_FILE);
@@ -53,7 +61,7 @@ function planningObligations() {
   ];
 }
 
-function executionObligations(plan) {
+function executionObligations(plan, stepBindingsEnabled = false) {
   return [
     {
       id: 'execute',
@@ -61,7 +69,7 @@ function executionObligations(plan) {
       requirement: 'Resolve the planned requirement fragments using adaptive Skill/direct-action bindings.',
       required: true,
       escapable: true,
-      suggestedSkills: suggestedBindings(plan, 'execution'),
+      suggestedSkills: stepBindingsEnabled ? [] : suggestedBindings(plan, 'execution'),
     },
     {
       id: 'verify',
@@ -69,7 +77,7 @@ function executionObligations(plan) {
       requirement: 'Produce objective verification evidence appropriate to the completed requirements before claiming completion.',
       required: true,
       escapable: false,
-      suggestedSkills: suggestedBindings(plan, 'verification'),
+      suggestedSkills: stepBindingsEnabled ? [] : suggestedBindings(plan, 'verification'),
     },
   ];
 }
@@ -117,7 +125,7 @@ function initializePlanningContract(context, plan) {
   return set;
 }
 
-function parseRequirements(requirementsJson) {
+function parseRequirements(requirementsJson, workspaceRoot) {
   let parsed;
   try { parsed = JSON.parse(String(requirementsJson || '')); }
   catch (_) { throw new Error('--requirements-json must be valid JSON'); }
@@ -136,15 +144,135 @@ function parseRequirements(requirementsJson) {
     const suggestedSkills = Array.isArray(item.suggestedSkills)
       ? [...new Set(item.suggestedSkills.filter(value => typeof value === 'string' && value.trim()).map(value => value.trim()))]
       : [];
-    return { id, order: index + 1, summary, acceptance, suggestedSkills };
+    const rawStepType = item.stepType === undefined ? '' : String(item.stepType).trim();
+    if (rawStepType && !STEP_TYPES.has(rawStepType)) throw new Error(`unsupported requirement stepType: ${rawStepType}`);
+    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`);
+      }
+    }
+    const requirement = { id, order: index + 1, summary, acceptance, suggestedSkills };
+    if (!rawStepType) return requirement;
+
+    const requiredBindings = normalizeBindingDeclarations([
+      ...(REQUIRED_BINDINGS_BY_STEP[rawStepType] || []),
+      ...(item.requiredBindings || []),
+    ]);
+    const requiredIds = new Set(requiredBindings.map(binding => binding.id));
+    const optionalBindings = normalizeBindingDeclarations([
+      ...(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');
+    }
+    requirement.stepType = rawStepType;
+    requirement.status = 'pending';
+    requirement.evidence = null;
+    requirement.reasonCode = null;
+    requirement.updatedAt = null;
+    requirement.requiredBindings = requiredBindings.map(binding => newBinding(binding.id, true, binding.path, workspaceRoot));
+    requirement.optionalBindings = optionalBindings.map(binding => newBinding(binding.id, false, binding.path, workspaceRoot));
+    return requirement;
+  });
+}
+
+function normalizeBindingPath(value) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('binding paths must be non-empty repository-relative strings');
+  const normalized = value.trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/g, '');
+  const parts = normalized.split('/');
+  if (!normalized || normalized.startsWith('/') || /^[A-Za-z]:/.test(normalized) ||
+      parts.some(part => !part || part === '.' || part === '..') || /[*?\[\]]/.test(normalized)) {
+    throw new Error(`binding path must be a concrete repository-relative path: ${value}`);
+  }
+  return normalized;
+}
+
+function normalizeBindingDeclarations(values) {
+  const result = [];
+  const byId = new Map();
+  for (const value of values || []) {
+    const bindingId = typeof value === 'string' ? value.trim()
+      : value && typeof value === 'object' && typeof value.id === 'string' ? value.id.trim() : '';
+    if (!SAFE_ID.test(bindingId)) throw new Error('binding ids must be stable identifier strings');
+    const bindingPath = value && typeof value === 'object' && value.path !== undefined && value.path !== null
+      ? normalizeBindingPath(value.path)
+      : null;
+    if (byId.has(bindingId)) {
+      const existing = byId.get(bindingId);
+      if (existing.path && bindingPath && existing.path !== bindingPath) throw new Error(`binding ${bindingId} declares conflicting paths`);
+      if (!existing.path && bindingPath) existing.path = bindingPath;
+      continue;
+    }
+    const declaration = { id: bindingId, path: bindingPath };
+    byId.set(bindingId, declaration);
+    result.push(declaration);
+  }
+  return result;
+}
+
+function newBinding(id, required, declaredPath = null, workspaceRoot = null) {
+  if (declaredPath && BINDING_PATHS[id] && declaredPath !== BINDING_PATHS[id]) {
+    throw new Error(`binding ${id} must use its registered path ${BINDING_PATHS[id]}`);
+  }
+  const bindingPath = declaredPath || BINDING_PATHS[id] || null;
+  const resolution = resolveBinding({ id, path: bindingPath }, workspaceRoot);
+  return {
+    id,
+    required,
+    status: 'pending',
+    path: bindingPath,
+    availability: resolution.availability,
+    resolvedPath: resolution.file,
+    evidence: null,
+    reasonCode: null,
+    updatedAt: null,
+  };
+}
+
+function activeStepRecord(set) {
+  if (!set?.stepBindingsEnabled) return null;
+  return set.requirements.find(item => item.stepType && item.status !== 'pass') || null;
+}
+
+function activeStepSnapshot(set) {
+  const step = activeStepRecord(set);
+  if (!step) return null;
+  const visibleBinding = binding => ({
+    id: binding.id,
+    status: binding.status,
+    availability: binding.availability,
+    path: binding.path,
+    resolvedPath: binding.resolvedPath || null,
   });
+  return {
+    id: step.id,
+    order: step.order,
+    stepType: step.stepType,
+    summary: step.summary,
+    completionCriteria: step.acceptance,
+    status: step.status,
+    requiredBindings: step.requiredBindings.map(visibleBinding),
+    optionalBindings: step.optionalBindings.map(visibleBinding),
+  };
 }
 
 function recordPlanning(context, requirementsJson, selectedPlan, requestedStrategy, evidence) {
   if (!needsPlanningContract(selectedPlan)) throw new Error('selected workflow does not require a planning contract');
   const loaded = loadObligationSet(context, selectedPlan);
   if (!loaded.set) throw new Error('workflow planning contract unavailable or invalid: ' + loaded.error);
-  const requirements = parseRequirements(requirementsJson);
+  const requirements = parseRequirements(requirementsJson, context.root);
+  const hasTypedSteps = requirements.some(item => item.stepType);
+  if (hasTypedSteps && requirements.some(item => !item.stepType)) {
+    throw new Error('all requirement fragments must declare stepType when step bindings are used');
+  }
+  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');
+  }
+  if (!isFable && !requirements.some(item => item.stepType === 'verification')) {
+    throw new Error('step-bound workflows require an explicit verification step');
+  }
   const requested = String(requestedStrategy || '').trim();
   const planningEvidence = String(evidence || '').trim();
   if (!requested) throw new Error('--strategy is required');
@@ -152,6 +280,8 @@ function recordPlanning(context, requirementsJson, selectedPlan, requestedStrate
 
   const now = new Date().toISOString();
   loaded.set.requirements = requirements;
+  loaded.set.stepBindingsEnabled = hasTypedSteps && !isFable;
+  loaded.set.activeStepId = null;
   const decompose = loaded.set.obligations.find(item => item.id === 'decompose');
   if (decompose) {
     decompose.status = 'pass';
@@ -202,12 +332,18 @@ function materializeExecutionObligations(context, plan) {
   if (!loaded.set) throw new Error('workflow planning contract unavailable or invalid: ' + loaded.error);
   if (planningUnresolved(context, plan).length) throw new Error('requirements/workflow planning must be resolved before start');
   const existing = new Map(loaded.set.obligations.map(item => [item.id, item]));
-  for (const item of executionObligations(plan)) {
+  for (const item of executionObligations(plan, loaded.set.stepBindingsEnabled === true)) {
     if (!existing.has(item.id)) loaded.set.obligations.push(newObligation(item));
+    else if (loaded.set.stepBindingsEnabled === true) {
+      const current = existing.get(item.id);
+      current.suggestedSkills = [];
+    }
   }
+  syncTypedAggregateObligations(loaded.set);
   loaded.set.phase = 'execution';
   loaded.set.activeStrategy = plan.strategy;
   loaded.set.revision = context.workflow.revision;
+  loaded.set.activeStepId = activeStepRecord(loaded.set)?.id || null;
   atomicWriteJson(obligationPath(context.sessionDir), loaded.set);
   return loaded.set;
 }
@@ -223,6 +359,30 @@ function validateObligationSet(context, set, plan = context.workflow?.pendingPla
     ids.add(obligation.id);
     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) ||
+        !['pending', 'pass', 'blocked'].includes(item.status) || !Array.isArray(item.requiredBindings) ||
+        !Array.isArray(item.optionalBindings))) return 'steps-invalid';
+    for (const step of set.requirements) {
+      for (const binding of [...step.requiredBindings, ...step.optionalBindings]) {
+        if (!binding || !SAFE_ID.test(binding.id || '') || !['pending', 'loaded', 'not-needed', 'unavailable'].includes(binding.status)) {
+          return 'step-binding-invalid';
+        }
+        if (binding.path !== null && typeof binding.path === 'string') {
+          try { if (normalizeBindingPath(binding.path) !== binding.path) return 'step-binding-path-invalid'; }
+          catch (_) { return 'step-binding-path-invalid'; }
+        } else if (binding.path !== null) return 'step-binding-path-invalid';
+        if (binding.resolvedPath !== undefined && binding.resolvedPath !== null && typeof binding.resolvedPath !== 'string') return 'step-binding-path-invalid';
+        if (binding.status === 'loaded' && !binding.path && !binding.resolvedPath) return 'step-binding-unknown-loaded';
+      }
+      if (step.status === 'pass' && (!step.evidence ||
+          step.requiredBindings.some(binding => binding.status !== 'loaded') ||
+          step.optionalBindings.some(binding => !['loaded', 'not-needed'].includes(binding.status)))) {
+        return 'step-resolution-invalid';
+      }
+    }
+    if (set.phase === 'execution' && set.activeStepId !== (activeStepRecord(set)?.id || null)) return 'active-step-invalid';
+  }
   return null;
 }
 
@@ -278,6 +438,113 @@ function updateObligation(context, obligationId, disposition, options = {}) {
   return obligation;
 }
 
+function updateBinding(context, stepId, bindingId, disposition, options = {}) {
+  if (!SAFE_ID.test(stepId || '') || !SAFE_ID.test(bindingId || '')) throw new Error('step and binding ids must be stable identifiers');
+  if (!['loaded', 'not-needed', 'unavailable'].includes(disposition)) {
+    throw new Error('--disposition must be loaded, not-needed, or unavailable');
+  }
+  const plan = context.workflow?.pendingPlan || context.workflow?.workflowPlan;
+  const loaded = loadObligationSet(context, plan);
+  if (!loaded.set) throw new Error('workflow obligation contract unavailable or invalid: ' + loaded.error);
+  if (!loaded.set.stepBindingsEnabled) throw new Error('workflow has no active-step binding contract');
+  const step = activeStepRecord(loaded.set);
+  if (!step || step.id !== stepId) throw new Error('bindings may only be resolved for the active step');
+  const binding = [...step.requiredBindings, ...step.optionalBindings].find(item => item.id === bindingId);
+  if (!binding) throw new Error('binding is not declared on the active step');
+  const evidence = String(options.evidence || '').trim();
+  if (!evidence) throw new Error('--evidence is required for every binding disposition');
+  if (binding.required && disposition === 'not-needed') throw new Error('required bindings cannot be marked not-needed');
+  if (!binding.required && disposition === 'unavailable') throw new Error('optional bindings require loaded or not-needed disposition');
+  if (disposition === 'loaded') {
+    const resolution = resolveBinding(binding, context.root);
+    if (resolution.availability !== 'available') {
+      const reasonCode = resolution.availability === 'unknown' ? 'binding-path-unknown' : 'binding-path-missing';
+      if (binding.required) {
+        binding.status = 'unavailable';
+        binding.availability = resolution.availability;
+        binding.resolvedPath = null;
+        binding.evidence = evidence;
+        binding.reasonCode = reasonCode;
+        binding.updatedAt = new Date().toISOString();
+        atomicWriteJson(obligationPath(context.sessionDir), loaded.set);
+      }
+      throw new Error(resolution.availability === 'unknown'
+        ? `${binding.required ? 'required' : 'optional'} binding ${binding.id} has no registered load path`
+        : `${binding.required ? 'required' : 'optional'} binding ${binding.id} path ${binding.path || binding.id} does not resolve to a readable file`);
+    }
+    binding.availability = 'available';
+    binding.resolvedPath = resolution.file;
+  }
+  binding.status = disposition;
+  binding.evidence = evidence;
+  binding.reasonCode = disposition === 'unavailable' ? String(options.reasonCode || 'binding-unavailable') : null;
+  binding.updatedAt = new Date().toISOString();
+  atomicWriteJson(obligationPath(context.sessionDir), loaded.set);
+  return { binding, activeStep: activeStepSnapshot(loaded.set) };
+}
+
+function syncTypedAggregateObligations(set) {
+  if (set.stepBindingsEnabled !== true) return;
+  const steps = set.requirements.filter(item => item?.stepType);
+  const groups = [
+    {
+      id: 'execute',
+      steps: steps.filter(step => step.stepType !== 'verification'),
+      evidencePrefix: 'typed-execution-steps',
+    },
+    {
+      id: 'verify',
+      steps: steps.filter(step => step.stepType === 'verification'),
+      evidencePrefix: 'typed-verification-steps',
+    },
+  ];
+  const now = new Date().toISOString();
+  for (const group of groups) {
+    const noExecutionStep = group.id === 'execute' && group.steps.length === 0;
+    if (!noExecutionStep && (!group.steps.length || !group.steps.every(step => step.status === 'pass' && step.evidence))) continue;
+    const obligation = set.obligations.find(item => item.id === group.id);
+    if (!obligation) continue;
+    obligation.status = 'pass';
+    obligation.evidence = noExecutionStep
+      ? 'typed-execution-steps:none (verification-only workflow)'
+      : `${group.evidencePrefix}:${group.steps.map(step => step.id).join(',')}`;
+    obligation.reasonCode = null;
+    obligation.scope = null;
+    obligation.updatedAt = now;
+  }
+}
+
+function updateStep(context, stepId, disposition, options = {}) {
+  if (!SAFE_ID.test(stepId || '')) throw new Error('--step-id must be a stable requirement id');
+  if (!['pass', 'blocked'].includes(disposition)) throw new Error('--disposition must be pass or blocked');
+  const plan = context.workflow?.pendingPlan || context.workflow?.workflowPlan;
+  const loaded = loadObligationSet(context, plan);
+  if (!loaded.set) throw new Error('workflow obligation contract unavailable or invalid: ' + loaded.error);
+  if (!loaded.set.stepBindingsEnabled) throw new Error('workflow has no active-step contract');
+  const step = activeStepRecord(loaded.set);
+  if (!step || step.id !== stepId) throw new Error('only the active step may receive a disposition');
+  const evidence = String(options.evidence || '').trim();
+  if (!evidence) throw new Error('--evidence is required for every step disposition');
+  const reasonCode = String(options.reasonCode || '').trim() || null;
+  if (disposition === 'blocked' && !reasonCode) throw new Error('--reason-code is required when blocking a step');
+  if (disposition === 'pass') {
+    const unresolvedRequired = step.requiredBindings.filter(binding => binding.status !== 'loaded');
+    const unresolvedOptional = step.optionalBindings.filter(binding => !['loaded', 'not-needed'].includes(binding.status));
+    if (unresolvedRequired.length || unresolvedOptional.length) {
+      const ids = [...unresolvedRequired, ...unresolvedOptional].map(binding => binding.id);
+      throw new Error('resolve active-step bindings before passing the step: ' + ids.join(', '));
+    }
+  }
+  step.status = disposition;
+  step.evidence = evidence;
+  step.reasonCode = reasonCode;
+  step.updatedAt = new Date().toISOString();
+  syncTypedAggregateObligations(loaded.set);
+  loaded.set.activeStepId = activeStepRecord(loaded.set)?.id || null;
+  atomicWriteJson(obligationPath(context.sessionDir), loaded.set);
+  return { step, activeStep: activeStepSnapshot(loaded.set) };
+}
+
 function unresolvedObligations(context) {
   const plan = context.workflow?.pendingPlan || context.workflow?.workflowPlan;
   if (!needsPlanningContract(plan)) return [];
@@ -297,6 +564,21 @@ function unresolvedObligations(context) {
       }
     }
   }
+  if (loaded.set.stepBindingsEnabled === true) {
+    const activeStep = activeStepRecord(loaded.set);
+    if (activeStep) {
+      if (activeStep.status === 'blocked') unresolved.push('step:' + activeStep.id + ':blocked');
+      else unresolved.push('step:' + activeStep.id + ':pending');
+      for (const binding of activeStep.requiredBindings) {
+        if (binding.status !== 'loaded') unresolved.push('binding:' + activeStep.id + ':' + binding.id + ':' + binding.status);
+      }
+      for (const binding of activeStep.optionalBindings) {
+        if (!['loaded', 'not-needed'].includes(binding.status)) {
+          unresolved.push('optional-binding:' + activeStep.id + ':' + binding.id + ':' + binding.status);
+        }
+      }
+    }
+  }
   return [...new Set(unresolved)];
 }
 
@@ -312,5 +594,8 @@ module.exports = {
   loadObligationSet,
   planningUnresolved,
   updateObligation,
+  updateBinding,
+  updateStep,
+  activeStepSnapshot,
   unresolvedObligations,
 };

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

@@ -7,7 +7,7 @@ const { atomicWriteJson, readJson } = require('./fable-contracts');
 
 const OPEN_STATES = new Set(['pending', 'active', 'running', 'failed', 'blocked', 'escaped']);
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const WORKFLOW_CONTROLLER_COMMANDS = new Set(['plan', 'start', 'revision', 'obligation', 'escape', 'block']);
+const WORKFLOW_CONTROLLER_COMMANDS = new Set(['plan', 'start', 'revision', 'obligation', 'binding', 'stage-binding', 'step', 'escape', 'block']);
 
 function activeWorkflowPlan(workflow) {
   if (!workflow) return null;
@@ -99,6 +99,13 @@ function unresolvedStages(match, workflow, lastEditAt = 0) {
     const escape = (workflow.escapes || []).find(item => item.stageId === stageId && item.runId === match.run.runId);
     if (escape && escape.evidence && escape.uncoveredScope &&
         ['workflow-uncovered-scope', 'host-capability-unavailable'].includes(escape.reasonCode)) continue;
+    const bindings = [...(contract.requiredBindings || []), ...(contract.optionalBindings || [])];
+    const unresolvedBindings = bindings.filter(binding => binding.required !== false
+      ? binding.status !== 'loaded'
+      : !['loaded', 'not-needed'].includes(binding.status));
+    if (unresolvedBindings.length) {
+      unresolved.push(`${stageId}:binding-unresolved:${unresolvedBindings.map(binding => binding.id).join(',')}`);
+    }
     const evidence = readJson(path.join(match.runRoot, 'evidence', `${stageId}.json`));
     if (contract.status !== 'pass' || !contract.checkCommand || !evidence || evidence.status !== 'pass' ||
         evidence.exitCode !== 0 || evidence.planId !== contract.planId || evidence.runId !== contract.runId ||