harness-everything 0.30.9 → 0.31.0

package/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/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 ||

package/hooks/scripts/workflow-disposition.js

@@ -6,11 +6,15 @@ const path = require('path');
 const { loadWorkflow, saveWorkflow, matchingRun, OPEN_STATES, WORKFLOW_CONTROLLER_COMMANDS } = require('./lib/workflow-runtime');
 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');
 
 const ALLOWED_ESCAPE_REASONS = new Set(['workflow-uncovered-scope', 'host-capability-unavailable']);
@@ -21,6 +25,7 @@ function parseArgs(argv) {
     ['--reason-code', 'reasonCode'], ['--scope', 'scope'], ['--evidence', 'evidence'],
     ['--session-id', 'sessionId'], ['--stage-id', 'stageId'],
     ['--obligation-id', 'obligationId'], ['--disposition', 'disposition'],
+    ['--step-id', 'stepId'], ['--binding-id', 'bindingId'],
     ['--requirements-json', 'requirementsJson'], ['--strategy', 'strategy'],
   ]);
   for (let i = 1; i < argv.length; i++) {
@@ -32,7 +37,7 @@ function parseArgs(argv) {
 }
 
 function usage() {
-  return `Usage: workflow-disposition.js <${[...WORKFLOW_CONTROLLER_COMMANDS].join('|')}> --session-id <id> [--requirements-json <json> --strategy <strategy> --obligation-id <id> --disposition <pass|escaped|blocked> --reason-code <reason> --scope <scope> --evidence <evidence>]`;
+  return `Usage: workflow-disposition.js <${[...WORKFLOW_CONTROLLER_COMMANDS].join('|')}> --session-id <id> [--requirements-json <json> --strategy <strategy> --obligation-id <id> --step-id <id> --binding-id <id> --disposition <pass|blocked|escaped|loaded|not-needed|unavailable> --reason-code <reason> --scope <scope> --evidence <evidence>]`;
 }
 
 const SELECTABLE_STRATEGIES = new Set(['direct-single', 'iterative-single', 'fable-staged', 'fable-parallel', 'fable-multi-agent-workspace']);
@@ -65,6 +70,7 @@ function recomposePlan(workflow, requestedStrategy) {
     taskShape,
     actionGateReasonCodes: workflow.workflowPlan.actionGate?.reasonCodes || [],
     reasonCodes: ['post-decomposition-workflow-selection'],
+    knowledgeSignals: workflow.workflowPlan.knowledgeSignals || [],
   });
 }
 
@@ -76,6 +82,61 @@ function consumer() {
   throw new Error('Fable consumer unavailable');
 }
 
+function stageBindingDisposition(context, args) {
+  if (!String(context.workflow.strategy || '').startsWith('fable-')) throw new Error('stage bindings are only available on Fable workflows');
+  if (context.workflow.state !== 'running') throw new Error('start the selected Fable workflow before resolving stage bindings');
+  const match = matchingRun(context);
+  if (!match || !match.run.stageIds.includes(args.stageId)) throw new Error('--stage-id must name a stage in the correlated active run');
+  if (!['loaded', 'not-needed', 'unavailable'].includes(args.disposition)) throw new Error('--disposition must be loaded, not-needed, or unavailable');
+  const evidence = String(args.evidence || '').trim();
+  if (!evidence) throw new Error('--evidence is required for every binding disposition');
+  const active = consumer().activeStageBindings(match.runRoot, context.workflow.escapes);
+  if (!active.some(stage => stage.stageId === args.stageId)) throw new Error('stage bindings may only be resolved for a dependency-ready active stage');
+  const contractPath = path.join(match.runRoot, 'contracts', `${args.stageId}.json`);
+  const contract = readJson(contractPath);
+  if (!contract || contract.runId !== match.run.runId || contract.stageId !== args.stageId) throw new Error('stage contract is missing or uncorrelated');
+  const binding = [...(contract.requiredBindings || []), ...(contract.optionalBindings || [])]
+    .find(item => item.id === args.bindingId);
+  if (!binding) throw new Error('--binding-id must name a binding declared on the stage');
+  const required = binding.required !== false;
+  if (required && args.disposition === 'not-needed') throw new Error('required bindings cannot be marked not-needed');
+  if (!required && args.disposition === 'unavailable') throw new Error('optional bindings require loaded or not-needed disposition');
+
+  let disposition = args.disposition;
+  let reasonCode = disposition === 'unavailable' ? String(args.reasonCode || 'binding-unavailable') : null;
+  let availability = disposition === 'unavailable' ? 'unavailable' : binding.availability;
+  if (disposition === 'loaded') {
+    const resolution = resolveBinding(binding, context.root);
+    availability = resolution.availability;
+    binding.resolvedPath = resolution.file;
+    if (resolution.availability !== 'available') {
+      disposition = 'unavailable';
+      reasonCode = resolution.availability === 'unknown' ? 'binding-path-unknown' : 'binding-path-missing';
+    }
+  }
+  binding.status = disposition;
+  binding.availability = availability;
+  binding.evidence = evidence;
+  binding.reasonCode = reasonCode;
+  binding.updatedAt = new Date().toISOString();
+  contract.updatedAt = binding.updatedAt;
+  atomicWriteJson(contractPath, contract);
+  return {
+    stageId: contract.stageId,
+    binding: { id: binding.id, required, status: binding.status, availability: binding.availability, path: binding.path, resolvedPath: binding.resolvedPath || null, reasonCode: binding.reasonCode },
+    activeStages: consumer().activeStageBindings(match.runRoot, context.workflow.escapes),
+  };
+}
+
+function activeStepCommandHints(sessionId, activeStep) {
+  if (!activeStep) return null;
+  const controller = path.resolve(__filename);
+  return {
+    resolveBinding: `node "${controller}" binding --session-id "${sessionId}" --step-id "${activeStep.id}" --binding-id "<active-binding-id>" --disposition <loaded|not-needed|unavailable> --evidence "<binding evidence>"`,
+    passStep: `node "${controller}" step --session-id "${sessionId}" --step-id "${activeStep.id}" --disposition pass --evidence "<completion evidence>"`,
+  };
+}
+
 function activatePlan(workflow, plan) {
   workflow.workflowPlan = plan;
   workflow.strategy = plan.strategy;
@@ -129,11 +190,14 @@ function main() {
       delete workflow.blockReason;
       const obligations = materializeExecutionObligations(context, plan);
       saveWorkflow(context);
+      const activeStep = activeStepSnapshot(obligations);
       process.stdout.write(JSON.stringify({
         state: workflow.state,
         workflowId: workflow.workflowId,
         revision: workflow.revision,
         obligations: obligations ? obligations.obligations.map(item => ({ id: item.id, status: item.status })) : [],
+        activeStep,
+        activeStepCommands: activeStepCommandHints(sessionId, activeStep),
       }) + '\n');
       return;
     }
@@ -156,6 +220,11 @@ function main() {
     workflow.escapes = [];
     delete workflow.pendingPlan;
     delete workflow.blockReason;
+  } else if (args.command === 'stage-binding') {
+    const result = stageBindingDisposition(context, args);
+    saveWorkflow(context);
+    process.stdout.write(JSON.stringify({ state: workflow.state, workflowId: workflow.workflowId, runId: workflow.runId, ...result }) + '\n');
+    return;
   } else if (args.command === 'obligation') {
     if (String(workflow.strategy || '').startsWith('fable-')) throw new Error('Fable workflows use correlated stage contracts, not generic execution obligations');
     if (workflow.state !== 'running') throw new Error('start the selected workflow before recording execution obligation dispositions');
@@ -175,6 +244,46 @@ function main() {
       },
     }) + '\n');
     return;
+  } else if (args.command === 'binding') {
+    if (String(workflow.strategy || '').startsWith('fable-')) throw new Error('Fable workflows use correlated stage contracts, not generic step bindings');
+    if (workflow.state !== 'running') throw new Error('start the selected workflow before resolving step bindings');
+    const result = updateBinding(context, args.stepId, args.bindingId, args.disposition, {
+      evidence: args.evidence,
+      reasonCode: args.reasonCode,
+    });
+    process.stdout.write(JSON.stringify({
+      state: workflow.state,
+      workflowId: workflow.workflowId,
+      binding: {
+        id: result.binding.id,
+        status: result.binding.status,
+        availability: result.binding.availability,
+        resolvedPath: result.binding.resolvedPath || null,
+        evidence: result.binding.evidence,
+      },
+      activeStep: result.activeStep,
+      activeStepCommands: activeStepCommandHints(sessionId, result.activeStep),
+    }) + '\n');
+    return;
+  } else if (args.command === 'step') {
+    if (String(workflow.strategy || '').startsWith('fable-')) throw new Error('Fable workflows use correlated stage contracts, not generic step dispositions');
+    if (workflow.state !== 'running') throw new Error('start the selected workflow before recording step dispositions');
+    const result = updateStep(context, args.stepId, args.disposition, {
+      evidence: args.evidence,
+      reasonCode: args.reasonCode,
+    });
+    process.stdout.write(JSON.stringify({
+      state: workflow.state,
+      workflowId: workflow.workflowId,
+      step: {
+        id: result.step.id,
+        status: result.step.status,
+        evidence: result.step.evidence,
+      },
+      activeStep: result.activeStep,
+      activeStepCommands: activeStepCommandHints(sessionId, result.activeStep),
+    }) + '\n');
+    return;
   } else if (args.command === 'revision') {
     console.error('[Workflow Reminder] Revision requested; no hard revision budget is enforced.');
   } else if (args.command === 'escape') {
@@ -198,7 +307,12 @@ function main() {
   } else throw new Error(usage());
 
   saveWorkflow(context);
-  process.stdout.write(JSON.stringify({ state: workflow.state, workflowId: workflow.workflowId, runId: workflow.runId, revision: workflow.revision, escapes: workflow.escapes }) + '\n');
+  const match = matchingRun(context);
+  process.stdout.write(JSON.stringify({
+    state: workflow.state, workflowId: workflow.workflowId, runId: workflow.runId,
+    revision: workflow.revision, escapes: workflow.escapes,
+    activeStages: match && String(workflow.strategy || '').startsWith('fable-') ? consumer().activeStageBindings(match.runRoot, workflow.escapes) : undefined,
+  }) + '\n');
 }
 
 try { main(); } catch (error) { console.error('[Workflow Disposition] ' + error.message); process.exitCode = 2; }

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.30.9",
+  "version": "0.31.0",
   "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
   "main": "harness-everything/scripts/bootstrap.js",
   "bin": {

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

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