harness-everything 0.16.6 → 0.18.0

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

@@ -0,0 +1,316 @@
+'use strict';
+
+const path = require('path');
+const { atomicWriteJson, readJson } = require('./fable-contracts');
+
+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']);
+
+function obligationPath(sessionDir) {
+  return path.join(sessionDir, OBLIGATION_FILE);
+}
+
+function needsPlanningContract(plan) {
+  return Boolean(
+    plan &&
+    plan.strategySelection === 'selected' &&
+    ['tier2', 'tier3'].includes(plan.tier) &&
+    plan.strategy
+  );
+}
+
+function needsGenericExecutionObligations(plan) {
+  return needsPlanningContract(plan) && !String(plan.strategy).startsWith('fable-');
+}
+
+function suggestedBindings(plan, kind) {
+  const skills = Array.isArray(plan?.suggestedSkills) ? plan.suggestedSkills : [];
+  if (kind === 'verification') return skills.filter(skill => skill === 'verification-loop');
+  if (kind === 'execution') return skills.filter(skill => skill !== 'verification-loop');
+  return [];
+}
+
+function planningObligations() {
+  return [
+    {
+      id: 'decompose',
+      kind: 'planning',
+      requirement: 'Decompose the user intent into explicit requirement fragments with acceptance evidence.',
+      required: true,
+      escapable: false,
+      suggestedSkills: [],
+    },
+    {
+      id: 'compose',
+      kind: 'planning',
+      requirement: 'Evaluate the requirement fragments and confirm the smallest sufficient workflow before execution.',
+      required: true,
+      escapable: false,
+      suggestedSkills: [],
+    },
+  ];
+}
+
+function executionObligations(plan) {
+  return [
+    {
+      id: 'execute',
+      kind: 'execution',
+      requirement: 'Resolve the planned requirement fragments using adaptive Skill/direct-action bindings.',
+      required: true,
+      escapable: true,
+      suggestedSkills: suggestedBindings(plan, 'execution'),
+    },
+    {
+      id: 'verify',
+      kind: 'verification',
+      requirement: 'Produce objective verification evidence appropriate to the completed requirements before claiming completion.',
+      required: true,
+      escapable: false,
+      suggestedSkills: suggestedBindings(plan, 'verification'),
+    },
+  ];
+}
+
+function newObligation(item) {
+  return {
+    ...item,
+    status: 'pending',
+    evidence: null,
+    reasonCode: null,
+    scope: null,
+    updatedAt: null,
+  };
+}
+
+function initializePlanningContract(context, plan) {
+  if (!needsPlanningContract(plan)) return null;
+  const existing = readJson(obligationPath(context.sessionDir));
+  if (existing && validateObligationSet(context, existing, plan) === null) return existing;
+  const now = new Date().toISOString();
+  const set = {
+    schemaVersion: OBLIGATION_SCHEMA_VERSION,
+    workflowId: context.workflow.workflowId,
+    sessionId: context.sessionId,
+    tier: plan.tier,
+    candidateStrategy: plan.strategy,
+    revision: context.workflow.revision,
+    phase: 'planning',
+    createdAt: now,
+    requirements: [],
+    workflowSelection: {
+      candidateStrategy: plan.strategy,
+      confirmedStrategy: null,
+      evidence: null,
+      confirmedAt: null,
+    },
+    obligations: planningObligations().map(newObligation),
+  };
+  atomicWriteJson(obligationPath(context.sessionDir), set);
+  context.workflow.obligationContract = {
+    schemaVersion: OBLIGATION_SCHEMA_VERSION,
+    file: OBLIGATION_FILE,
+    revision: set.revision,
+  };
+  return set;
+}
+
+function parseRequirements(requirementsJson) {
+  let parsed;
+  try { parsed = JSON.parse(String(requirementsJson || '')); }
+  catch (_) { throw new Error('--requirements-json must be valid JSON'); }
+  if (!Array.isArray(parsed) || parsed.length < 1 || parsed.length > 32) {
+    throw new Error('--requirements-json must contain 1..32 requirement fragments');
+  }
+  const ids = new Set();
+  return parsed.map((item, index) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) throw new Error('requirement fragment must be an object');
+    const id = String(item.id || '').trim();
+    const summary = String(item.summary || '').trim();
+    const acceptance = String(item.acceptance || '').trim();
+    if (!SAFE_ID.test(id) || ids.has(id)) throw new Error('requirement ids must be unique stable ids');
+    if (!summary || !acceptance) throw new Error('each requirement needs summary and acceptance');
+    ids.add(id);
+    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 };
+  });
+}
+
+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 requested = String(requestedStrategy || '').trim();
+  const planningEvidence = String(evidence || '').trim();
+  if (!requested) throw new Error('--strategy is required');
+  if (!planningEvidence) throw new Error('--evidence is required');
+
+  const now = new Date().toISOString();
+  loaded.set.requirements = requirements;
+  const decompose = loaded.set.obligations.find(item => item.id === 'decompose');
+  if (decompose) {
+    decompose.status = 'pass';
+    decompose.reasonCode = null;
+    decompose.evidence = 'requirements:' + requirements.map(item => item.id).join(',');
+    decompose.updatedAt = now;
+  }
+
+  const blocked = selectedPlan.fallback?.disposition === 'blocked';
+  loaded.set.workflowSelection = {
+    candidateStrategy: loaded.set.candidateStrategy,
+    requestedStrategy: requested,
+    confirmedStrategy: blocked ? null : selectedPlan.strategy,
+    evidence: planningEvidence,
+    confirmedAt: blocked ? null : now,
+    disposition: blocked ? 'blocked' : 'confirmed',
+    fallback: selectedPlan.fallback || null,
+  };
+  const compose = loaded.set.obligations.find(item => item.id === 'compose');
+  if (compose) {
+    compose.status = blocked ? 'blocked' : 'pass';
+    compose.reasonCode = blocked ? 'workflow-selection-blocked' : null;
+    compose.evidence = planningEvidence;
+    compose.updatedAt = now;
+  }
+
+  if (blocked) {
+    context.workflow.planningWarning = 'workflow-selection-blocked';
+    delete context.workflow.pendingPlan;
+  } else {
+    loaded.set.phase = 'planned';
+    delete context.workflow.planningWarning;
+    if (selectedPlan.strategy !== context.workflow.workflowPlan.strategy ||
+        JSON.stringify(selectedPlan) !== JSON.stringify(context.workflow.workflowPlan)) {
+      context.workflow.pendingPlan = selectedPlan;
+    } else {
+      delete context.workflow.pendingPlan;
+    }
+  }
+
+  atomicWriteJson(obligationPath(context.sessionDir), loaded.set);
+  return { set: loaded.set, blocked, selectedPlan };
+}
+
+function materializeExecutionObligations(context, plan) {
+  if (!needsGenericExecutionObligations(plan)) return null;
+  const loaded = loadObligationSet(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)) {
+    if (!existing.has(item.id)) loaded.set.obligations.push(newObligation(item));
+  }
+  loaded.set.phase = 'execution';
+  loaded.set.activeStrategy = plan.strategy;
+  loaded.set.revision = context.workflow.revision;
+  atomicWriteJson(obligationPath(context.sessionDir), loaded.set);
+  return loaded.set;
+}
+
+function validateObligationSet(context, set, plan = context.workflow?.pendingPlan || context.workflow?.workflowPlan) {
+  if (!set || set.schemaVersion !== OBLIGATION_SCHEMA_VERSION) return 'schema-invalid';
+  if (set.workflowId !== context.workflow?.workflowId || set.sessionId !== context.sessionId) return 'correlation-invalid';
+  if (!plan || set.tier !== plan.tier) return 'plan-mismatch';
+  if (!Array.isArray(set.requirements) || !Array.isArray(set.obligations) || set.obligations.length === 0) return 'obligations-invalid';
+  const ids = new Set();
+  for (const obligation of set.obligations) {
+    if (!obligation || !SAFE_ID.test(obligation.id || '') || ids.has(obligation.id)) return 'obligation-id-invalid';
+    ids.add(obligation.id);
+    if (!['pending', 'pass', 'escaped', 'blocked'].includes(obligation.status)) return 'obligation-status-invalid';
+  }
+  return null;
+}
+
+function loadObligationSet(context, plan) {
+  const set = readJson(obligationPath(context.sessionDir));
+  const error = validateObligationSet(context, set, plan);
+  return { set: error ? null : set, error };
+}
+
+function planningUnresolved(context, plan = context.workflow?.pendingPlan || context.workflow?.workflowPlan) {
+  if (!needsPlanningContract(plan)) return [];
+  const loaded = loadObligationSet(context, plan);
+  if (!loaded.set) return ['planning:' + (loaded.error || 'missing')];
+  const unresolved = [];
+  for (const id of ['decompose', 'compose']) {
+    const obligation = loaded.set.obligations.find(item => item.id === id);
+    if (!obligation) unresolved.push(id + ':missing');
+    else if (obligation.status !== 'pass' || !obligation.evidence) unresolved.push(id + ':' + obligation.status);
+  }
+  if (!loaded.set.requirements.length) unresolved.push('requirements:empty');
+  if (loaded.set.workflowSelection?.confirmedStrategy !== plan.strategy ||
+      loaded.set.workflowSelection?.disposition !== 'confirmed') {
+    unresolved.push('workflow-selection:unconfirmed');
+  }
+  return [...new Set(unresolved)];
+}
+
+function updateObligation(context, obligationId, disposition, options = {}) {
+  if (!SAFE_ID.test(obligationId || '')) throw new Error('--obligation-id must be a stable obligation id');
+  if (!['pass', 'escaped', 'blocked'].includes(disposition)) throw new Error('--disposition must be pass, escaped, or blocked');
+  if (['decompose', 'compose'].includes(obligationId)) throw new Error('planning obligations are resolved through the plan command');
+  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);
+  const obligation = loaded.set.obligations.find(item => item.id === obligationId);
+  if (!obligation) throw new Error('unknown workflow obligation: ' + obligationId);
+  const evidence = String(options.evidence || '').trim();
+  if (!evidence) throw new Error('--evidence is required for every obligation disposition');
+  const reasonCode = String(options.reasonCode || '').trim() || null;
+  const scope = String(options.scope || '').trim() || null;
+  if (disposition === 'escaped') {
+    if (!obligation.escapable) throw new Error('this obligation cannot be escaped');
+    if (!ALLOWED_ESCAPE_REASONS.has(reasonCode)) throw new Error('escaped obligations require workflow-uncovered-scope or host-capability-unavailable');
+    if (!scope) throw new Error('--scope is required when escaping an obligation');
+  }
+  if (disposition === 'blocked' && !reasonCode) throw new Error('--reason-code is required when blocking an obligation');
+  obligation.status = disposition;
+  obligation.evidence = evidence;
+  obligation.reasonCode = reasonCode;
+  obligation.scope = scope;
+  obligation.updatedAt = new Date().toISOString();
+  atomicWriteJson(obligationPath(context.sessionDir), loaded.set);
+  return obligation;
+}
+
+function unresolvedObligations(context) {
+  const plan = context.workflow?.pendingPlan || context.workflow?.workflowPlan;
+  if (!needsPlanningContract(plan)) return [];
+  const unresolved = planningUnresolved(context, plan);
+  const loaded = loadObligationSet(context, plan);
+  if (!loaded.set) return unresolved;
+  if (!['running', 'satisfied', 'blocked', 'failed'].includes(context.workflow.state)) {
+    unresolved.push('execution:not-started');
+  }
+  if (needsGenericExecutionObligations(plan)) {
+    for (const obligation of loaded.set.obligations.filter(item => ['execute', 'verify'].includes(item.id))) {
+      if (obligation.status === 'pending') unresolved.push(obligation.id + ':pending');
+      else if (obligation.status === 'blocked') unresolved.push(obligation.id + ':blocked');
+      else if (!obligation.evidence) unresolved.push(obligation.id + ':evidence-missing');
+      else if (obligation.status === 'escaped' && (!obligation.escapable || !ALLOWED_ESCAPE_REASONS.has(obligation.reasonCode) || !obligation.scope)) {
+        unresolved.push(obligation.id + ':escape-invalid');
+      }
+    }
+  }
+  return [...new Set(unresolved)];
+}
+
+module.exports = {
+  OBLIGATION_FILE,
+  ALLOWED_ESCAPE_REASONS,
+  obligationPath,
+  needsPlanningContract,
+  needsGenericExecutionObligations,
+  initializePlanningContract,
+  recordPlanning,
+  materializeExecutionObligations,
+  loadObligationSet,
+  planningUnresolved,
+  updateObligation,
+  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(['start', 'revision', 'escape', 'block']);
+const WORKFLOW_CONTROLLER_COMMANDS = new Set(['plan', 'start', 'revision', 'obligation', 'escape', 'block']);
 
 function activeWorkflowPlan(workflow) {
   if (!workflow) return null;

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

@@ -6,22 +6,66 @@ 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 {
+  planningUnresolved,
+  recordPlanning,
+  materializeExecutionObligations,
+  updateObligation,
+} = require('./lib/workflow-obligations');
 
 const ALLOWED_ESCAPE_REASONS = new Set(['workflow-uncovered-scope', 'host-capability-unavailable']);
 
 function parseArgs(argv) {
   const args = { command: argv[0] };
-  const flags = new Map([['--reason-code', 'reasonCode'], ['--scope', 'scope'], ['--evidence', 'evidence'], ['--session-id', 'sessionId'], ['--stage-id', 'stageId']]);
+  const flags = new Map([
+    ['--reason-code', 'reasonCode'], ['--scope', 'scope'], ['--evidence', 'evidence'],
+    ['--session-id', 'sessionId'], ['--stage-id', 'stageId'],
+    ['--obligation-id', 'obligationId'], ['--disposition', 'disposition'],
+    ['--requirements-json', 'requirementsJson'], ['--strategy', 'strategy'],
+  ]);
   for (let i = 1; i < argv.length; i++) {
     const key = flags.get(argv[i]);
-    if (!key || !argv[i + 1] || argv[i + 1].startsWith('--')) throw new Error('unknown or incomplete argument: ' + argv[i]);
+    if (!key || argv[i + 1] === undefined || argv[i + 1].startsWith('--')) throw new Error('unknown or incomplete argument: ' + argv[i]);
     args[key] = argv[++i];
   }
   return args;
 }
 
 function usage() {
-  return `Usage: workflow-disposition.js <${[...WORKFLOW_CONTROLLER_COMMANDS].join('|')}> --session-id <id> [--stage-id <id> --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> --disposition <pass|escaped|blocked> --reason-code <reason> --scope <scope> --evidence <evidence>]`;
+}
+
+const SELECTABLE_STRATEGIES = new Set(['direct-single', 'iterative-single', 'fable-staged', 'fable-parallel', 'fable-multi-agent-workspace']);
+
+function routerContract() {
+  for (const relative of ['../../harness-everything/scripts/router-contract.js', '../../skills/harness-everything/scripts/router-contract.js']) {
+    const file = path.resolve(__dirname, relative);
+    if (fs.existsSync(file)) return require(file);
+  }
+  throw new Error('router contract unavailable');
+}
+
+function recomposePlan(workflow, requestedStrategy) {
+  const strategy = String(requestedStrategy || '').trim();
+  if (!SELECTABLE_STRATEGIES.has(strategy)) throw new Error('--strategy must name a supported execution topology');
+  if (strategy === workflow.workflowPlan.strategy) return workflow.workflowPlan;
+  if (!workflow.taskShape || typeof workflow.taskShape !== 'object') {
+    throw new Error('workflow task-shape context is unavailable; cannot safely recompose topology');
+  }
+  const taskShape = {
+    ...workflow.taskShape,
+    explicitRequest: {
+      ...(workflow.taskShape.explicitRequest || {}),
+      strategy,
+    },
+  };
+  return routerContract().buildWorkflowPlan({
+    routingStatus: workflow.workflowPlan.routingStatus,
+    tier: workflow.tier,
+    taskShape,
+    actionGateReasonCodes: workflow.workflowPlan.actionGate?.reasonCodes || [],
+    reasonCodes: ['post-decomposition-workflow-selection'],
+  });
 }
 
 function consumer() {
@@ -51,10 +95,31 @@ function main() {
   const context = loadWorkflow({ session_id: sessionId });
   const { workflow } = context;
   if (!workflow || !OPEN_STATES.has(workflow.state)) throw new Error('no unresolved workflow contract exists for this session');
+
+  if (args.command === 'plan') {
+    if (!workflow.workflowId || !workflow.workflowPlan) throw new Error('legacy workflow lacks a correlated plan; cannot plan it implicitly');
+    if (!['pending', 'active'].includes(workflow.state)) throw new Error('requirements/workflow composition belongs before execution starts');
+    const selectedPlan = recomposePlan(workflow, args.strategy);
+    const result = recordPlanning(context, args.requirementsJson, selectedPlan, args.strategy, args.evidence);
+    saveWorkflow(context);
+    process.stdout.write(JSON.stringify({
+      state: workflow.state,
+      workflowId: workflow.workflowId,
+      requirements: result.set.requirements.map(item => ({ id: item.id, summary: item.summary })),
+      workflowSelection: result.set.workflowSelection,
+      selectedStrategy: result.selectedPlan.strategy,
+      blocked: result.blocked,
+    }) + '\n');
+    return;
+  }
+
   if (args.command === 'start') {
     if (!workflow.workflowId || !workflow.workflowPlan) throw new Error('legacy workflow lacks a correlated plan; cannot start it implicitly');
     if (workflow.state === 'running') throw new Error('workflow already running; record a blocker before replanning');
     const plan = workflow.pendingPlan || workflow.workflowPlan;
+    const unresolvedPlanning = planningUnresolved(context, plan);
+    if (unresolvedPlanning.length) throw new Error('resolve requirement decomposition/workflow selection first: ' + unresolvedPlanning.join(', '));
+
     if (!String(plan.strategy || '').startsWith('fable-')) {
       activatePlan(workflow, plan);
       workflow.revision++;
@@ -62,10 +127,17 @@ function main() {
       workflow.escapes = [];
       delete workflow.pendingPlan;
       delete workflow.blockReason;
+      const obligations = materializeExecutionObligations(context, plan);
       saveWorkflow(context);
-      process.stdout.write(JSON.stringify({ state: workflow.state, workflowId: workflow.workflowId, revision: workflow.revision }) + '\n');
+      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 })) : [],
+      }) + '\n');
       return;
     }
+
     const stages = readJson(path.join(context.sessionDir, 'workflow-stages.json'));
     if (!Array.isArray(stages) || !stages.length) throw new Error('write a non-empty workflow-stages.json stage array at the session path first');
     if (stages.some(stage => !stage.checkCommand || !stage.passCondition)) throw new Error('every required stage needs an objective checkCommand and passCondition');
@@ -84,6 +156,25 @@ function main() {
     workflow.escapes = [];
     delete workflow.pendingPlan;
     delete workflow.blockReason;
+  } 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');
+    const obligation = updateObligation(context, args.obligationId, args.disposition, {
+      evidence: args.evidence,
+      reasonCode: args.reasonCode,
+      scope: args.scope,
+    });
+    process.stdout.write(JSON.stringify({
+      state: workflow.state,
+      workflowId: workflow.workflowId,
+      obligation: {
+        id: obligation.id,
+        status: obligation.status,
+        reasonCode: obligation.reasonCode,
+        evidence: obligation.evidence,
+      },
+    }) + '\n');
+    return;
   } else if (args.command === 'revision') {
     console.error('[Workflow Reminder] Revision requested; no hard revision budget is enforced.');
   } else if (args.command === 'escape') {
@@ -100,13 +191,14 @@ function main() {
     };
     workflow.escapes = [...(workflow.escapes || []).filter(item => item.stageId !== args.stageId), disposition];
     atomicWriteJson(path.join(match.runRoot, 'escapes', args.stageId + '.json'), disposition);
-    // Scope-limited exception; never change the entire workflow to escaped.
   } else if (args.command === 'block') {
     if (!args.evidence?.trim()) throw new Error('--evidence is required');
     workflow.state = 'blocked';
     workflow.blockReason = args.evidence.trim();
   } 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');
 }
+
 try { main(); } catch (error) { console.error('[Workflow Disposition] ' + error.message); process.exitCode = 2; }

package/plugins/harness-everything/hooks/scripts/workflow-stop-gate.js

@@ -3,7 +3,10 @@
 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');
+
 function warn(message) { console.error('[Workflow Reminder] ' + message); }
+
 function decide(payload) {
   if (!payload) return;
   try {
@@ -11,20 +14,24 @@ function decide(payload) {
     const { workflow, sessionDir } = context;
     if (!workflow || workflow.state === 'deferred') return;
     const handoff = readJson(path.join(sessionDir, 'handoff-state.json'));
-    let unresolved = [];
+    let unresolved = planningUnresolved(context);
+
     if (String(workflow.strategy || '').startsWith('fable-')) {
       const match = matchingRun(context);
-      unresolved = match ? unresolvedStages(match, workflow, handoff?.lastEditAt || 0) : ['correlated-run-missing'];
+      unresolved.push(...(match ? unresolvedStages(match, workflow, handoff?.lastEditAt || 0) : ['correlated-run-missing']));
     } else {
+      unresolved.push(...unresolvedObligations(context));
       const lastEdit = Math.max(workflow.lastMutationAt || 0, handoff?.lastEditAt || 0);
-      if (lastEdit && (handoff?.lastVerifyAt || 0) < lastEdit) unresolved = ['verification-after-edit-missing'];
+      if (lastEdit && (handoff?.lastVerifyAt || 0) < lastEdit) unresolved.push('verification-after-edit-missing');
     }
+
+    unresolved = [...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(', ') + '. Verify/review before claiming completion.');
+      warn('Unresolved workflow evidence: ' + unresolved.join(', ') + '. Resolve/verify before claiming completion.');
       return;
     }
     if (wasBlocked) return;
@@ -34,4 +41,5 @@ function decide(payload) {
     saveWorkflow(context);
   } catch (error) { warn(error && error.message ? error.message : String(error)); }
 }
+
 readHookInput(decide);

package/plugins/harness-everything/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "harness-everything",
-  "version": "0.16.6",
+  "version": "0.18.0",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/scripts/lib/advisory-text.js

@@ -15,7 +15,16 @@ const advisoryInstructions = [
   `2. For EVERY suggested skill, read its complete \`SKILL.md\` entry and evaluate applicability from \`USE FOR\`, \`DO NOT USE FOR\`, and its basic flow.`,
   `3. Treat the selected workflow topology and numeric limits as planning guidance, not a lock. Choose, combine, reorder, or skip steps when evidence supports it.`,
   `4. Prefer objective verification before declaring done and worktree isolation for broad/Tier-3 mutation.`,
-  `5. Surface a compact routing checkpoint with tier, strategy, suggested skills, and any relevant warnings.`,
+  `5. Use the routing checkpoint as source state for the first Harness Status; do not expose a competing progress format.`,
+  ``,
+  `## 📣 USER-VISIBLE STATUS (MUST)`,
+  `For non-trivial software/project work, this semantic communication contract is mandatory even when the host integration itself is instruction-only:`,
+  `- \`Harness Status\``,
+  `- \`Current:\` what is being done now`,
+  `- \`Read/Evidence:\` important files, sources, or evidence read/confirmed`,
+  `- \`Next:\` the next intended action`,
+  `- \`Blocked/Risk:\` only when materially applicable`,
+  `Emit it before substantive execution, after a major phase, when direction materially changes, at meaningful long-running phase boundaries, and before final completion. This MUST does not imply a hard runtime lock.`,
   ``,
   `## 🤖 COGNITIVE COMPLIANCE`,
   `- **No universal skill pipeline**: do not force every task through TODO/TDD/Fable.`,
@@ -135,7 +144,8 @@ function buildCodexGlobalContent() {
     `This instruction surface cannot be assumed to provide hard lifecycle blocking.`,
     ``,
     `- Discover the environment and host capabilities before relying on them.`,
-    `- For software/project work, run \`npx github:dyphn1/Harness-everything next "<summary>"\` before mutation and surface the routing checkpoint.`,
+    `- For software/project work, run \`npx github:dyphn1/Harness-everything next "<summary>"\` before mutation and use the routing checkpoint as source state for the first Harness Status.`,
+    `- For non-trivial work, MUST keep the user informed with one Harness Status shape: Current, Read/Evidence, Next, plus Blocked/Risk only when material; repeat it at major phase/direction boundaries and before final completion.`,
     `- Read every suggested skill's complete \`SKILL.md\` entry before resolving applicability; do not omit it from metadata or confidence alone.`,
     `- Use the selected workflow topology as planning guidance; the model may adapt or skip steps with an explicit evidence-based reason.`,
     `- Do not impose a universal TODO/TDD/Fable sequence; use the smallest useful topology plus applicable skills.`,

package/plugins/harness-everything/skills/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through the Harness kernel: classify T
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.16.6
+  version: 0.18.0
 ---
 
 # Harness Everything
@@ -23,11 +23,12 @@ Kernel routing entry.
 2. **Verify before claim** — seek objective evidence before saying work is done.
 3. **Zoom out on repetition** — after 3 same-signature failures, use `zoom-out`.
 4. **Evaluate before omission** — read each suggested skill's `SKILL.md` before deciding applicability.
-5. **Keep agency** — workflow state and numeric limits guide; they do not hard-stop execution.
+5. **Surface status** — non-trivial work MUST use one `Harness Status`: `Current`, `Read/Evidence`, `Next`, optional `Blocked/Risk`, at major phase/direction boundaries.
+6. **Keep agency** — workflow state and numeric limits guide; they do not hard-stop execution.
 
 ## Workflow
 1. Reuse kernel output, or run `node "<this-skill-dir>/scripts/kernel-router.js" "<prompt summary>"`.
-2. Surface the **Harness Routing Checkpoint**.
+2. Use the **Harness Routing Checkpoint** to populate the first Harness Status; it is not a second progress format.
 3. Read each suggested `SKILL.md`; evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules.
 4. Use the selected topology as planning guidance. Choose, combine, reorder, or skip steps when evidence supports doing so.
 5. Prefer worktree isolation for broad/Tier-3 mutation and objective verification before completion.

package/plugins/harness-everything/skills/harness-everything/references/triage-and-tiers.md

@@ -44,6 +44,7 @@ The kernel protects lifecycle obligations without micromanaging model reasoning.
 3. **Re-plan on repetition** — after three same-signature failures, stop micro-retrying and use a fresh diagnosis / `zoom-out`.
 4. **Evaluate before omission** — when the router suggests a skill, read its complete `SKILL.md` entry/basic flow before deciding applicability.
 5. **Review selected workflow** — use the topology as planning guidance and keep any skipped step evidence-based.
+6. **Surface status** — non-trivial software/project work MUST use the single Harness Status format at required phase boundaries.
 
 The model remains free to choose tools, implementation technique, decomposition details, and reasoning inside the workflow.
 
@@ -148,9 +149,25 @@ On Claude and the local OpenAI package, supported hooks observe workflow/worktre
 
 Never turn mechanism/package evidence into a cross-host live-enforcement claim. #82 owns host-specific retained evidence.
 
-## 6. Routing Checkpoint
+## 6. User-visible status contract
 
-For software/project work, surface this state before or with the first progress update:
+For non-trivial software/project work, user-facing progress **MUST** use one stable shape across direct, iterative, Fable, and multi-agent execution:
+
+```text
+Harness Status
+- Current: <what is being done now>
+- Read/Evidence: <important files/sources/evidence read or confirmed>
+- Next: <next intended action>
+- Blocked/Risk: <only when materially applicable>
+```
+
+Emit it before substantive execution, after a major phase completes, when the plan/assumption/direction materially changes, at meaningful phase boundaries during long-running work, and before final completion. The final response may merge the last status naturally.
+
+This is a semantic communication MUST. It does **not** create a runtime lock, counter, reset requirement, or permission boundary. The routing checkpoint below is source state for this format, not a second competing progress template.
+
+## 7. Routing Checkpoint
+
+For software/project work, consume this runtime state when producing the first Harness Status:
 
 ```markdown
 ## 🚦 Harness Routing Checkpoint
@@ -163,9 +180,9 @@ For software/project work, surface this state before or with the first progress
 - Escape: <none | reason + uncovered scope + evidence>
 ```
 
-The checkpoint is state, not a universal response template. The key distinction is: **skill suggestions are evaluated for applicability; a selected topology guides execution but does not trap it.**
+The checkpoint is runtime/source state, not a competing user-facing template. Render user progress through the single Harness Status contract above. The key distinction is: **skill suggestions are evaluated for applicability; a selected topology guides execution but does not trap it.**
 
-## 7. Self-Healing and Dynamic Skills
+## 8. Self-Healing and Dynamic Skills
 
 Self-heal, generated-skill discovery, knowledge-guide matching, and fact-audit behavior remain part of the runtime. Dynamic recommendations still require applicability evaluation.