harness-everything 0.16.6 → 0.17.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "harness-everything",
       "source": "./",
       "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-      "version": "0.16.6",
+      "version": "0.17.0",
       "author": {
         "name": "Miya Daniel"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-everything",
   "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-  "version": "0.16.6",
+  "version": "0.17.0",
   "author": {
     "name": "Miya Daniel"
   },

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.17.0](https://github.com/dyphn1/Harness-everything/compare/v0.16.6...v0.17.0) (2026-09-21)
+
+### Features
+
+* **router:** expose obligation resolution contract ([767f8ef](https://github.com/dyphn1/Harness-everything/commit/767f8ef20b97fe8da2dcbe11a49f00fd03d0976b))
+* **router:** retain task shape for post-decomposition composition ([cff0e48](https://github.com/dyphn1/Harness-everything/commit/cff0e489cdb5cd8a80b48370ab9905e508eac4e7))
+* **router:** surface requirements-first planning ([3ad82ae](https://github.com/dyphn1/Harness-everything/commit/3ad82aedbae7943b66cf686b05a685d247f8c0b0))
+* **workflow:** add non-Fable obligation contract ([d31bb0e](https://github.com/dyphn1/Harness-everything/commit/d31bb0e3b997a597692ae0af8741d5963bddc3aa))
+* **workflow:** add planning transition ([5f5855b](https://github.com/dyphn1/Harness-everything/commit/5f5855bb2219efcc6a0964319324e7d8215a775d))
+* **workflow:** confirm recomposed post-decomposition plan ([a5b2698](https://github.com/dyphn1/Harness-everything/commit/a5b26989da664c8f9e4c276210ba23fc67e2aeda))
+* **workflow:** decompose intent before start ([d1aba6d](https://github.com/dyphn1/Harness-everything/commit/d1aba6d01a2e3e260fc79b996b7e754fa3cd53e8))
+* **workflow:** expose obligation controller command ([4235144](https://github.com/dyphn1/Harness-everything/commit/42351443f315c130b302e120f382929f84cf5896))
+* **workflow:** keep unresolved obligations visible ([926dc2b](https://github.com/dyphn1/Harness-everything/commit/926dc2bb900b5891a3f217989216eeb5fc1917fd))
+* **workflow:** materialize and resolve obligations ([3cc25ad](https://github.com/dyphn1/Harness-everything/commit/3cc25ad18fa6325a6fd93b69749a7dadb605e099))
+* **workflow:** recompose topology after requirement decomposition ([bbb3ed7](https://github.com/dyphn1/Harness-everything/commit/bbb3ed7ca6bf9cfd24b8089428db0eb6b6cd52c0))
+* **workflow:** report unresolved planning obligations ([0c088d7](https://github.com/dyphn1/Harness-everything/commit/0c088d7cc7bf2c75631bf9b9b56dcd8b5851600a))
+
+### Bug Fixes
+
+* **workflow:** keep composition pre-execution ([a22e1de](https://github.com/dyphn1/Harness-everything/commit/a22e1de876bcc6a1bc36a6c679c2dcbcac1ce672))
+* **workflow:** keep recomposed pending execution unresolved ([f29672a](https://github.com/dyphn1/Harness-everything/commit/f29672a55d2b764a8e0dd909cd700af851bda415))
+* **workflow:** preserve decomposition before replan ([8400383](https://github.com/dyphn1/Harness-everything/commit/840038349cb11636152f68be560961f75a9859f2))
+
 ## [0.16.6](https://github.com/dyphn1/Harness-everything/compare/v0.16.5...v0.16.6) (2026-09-21)
 
 ### Bug Fixes

package/ci/mechanism-2ai-workspace-fingerprint-batch.test.js

@@ -188,8 +188,18 @@ try {
     prompt: 'Fix this checkout bug with a regression test',
   });
   check(routed.status === 0, '#169 large-workspace Tier-2 fixture routes normally');
+  const requirements = JSON.stringify([
+    { id: 'req-fingerprint', summary: 'Exercise large-workspace shell admission', acceptance: 'the shell call remains available above the fingerprint observation cap' },
+  ]);
+  const planned = node('hooks/scripts/workflow-disposition.js', undefined, [
+    'plan', '--session-id', sessionId,
+    '--requirements-json', requirements,
+    '--strategy', 'iterative-single',
+    '--evidence', 'single bounded runtime regression uses the iterative workflow',
+  ]);
+  check(planned.status === 0, '#169 large-workspace Tier-2 fixture resolves requirements/workflow planning');
   const started = node('hooks/scripts/workflow-disposition.js', undefined, ['start', '--session-id', sessionId]);
-  check(started.status === 0, '#169 large-workspace Tier-2 fixture starts normally');
+  check(started.status === 0, '#169 large-workspace Tier-2 fixture starts after planning');
 
   const admitted = node('hooks/scripts/workflow-gate.js', {
     ...payload,

package/ci/mechanism-2an-workflow-obligations.test.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const stateHome = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-issue85-obligations-'));
+process.env.HARNESS_STATE_HOME = stateHome;
+process.env.HARNESS_WORKSPACE_ROOT = ROOT;
+
+const { getSessionDir } = require(path.join(ROOT, 'hooks/scripts/lib/harness-state.js'));
+const kernel = path.join(ROOT, 'harness-everything/scripts/kernel-router.js');
+const controller = path.join(ROOT, 'hooks/scripts/workflow-disposition.js');
+const stopGate = path.join(ROOT, 'hooks/scripts/workflow-stop-gate.js');
+const workflowGate = path.join(ROOT, 'hooks/scripts/workflow-gate.js');
+const statePersist = path.join(ROOT, 'hooks/scripts/state-persist.js');
+
+let failed = 0;
+function check(condition, message) {
+  if (condition) console.log('  PASS ' + message);
+  else { console.error('  FAIL ' + message); failed++; }
+}
+function run(script, args = [], input = null) {
+  return spawnSync(process.execPath, [script, ...args], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    input: input === null ? undefined : JSON.stringify(input),
+    env: { ...process.env, HARNESS_STATE_HOME: stateHome, HARNESS_WORKSPACE_ROOT: ROOT },
+  });
+}
+function readJson(file) { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+
+console.log('=== Issue #85 requirements-first workflow contract ===');
+
+const sessionId = 'issue85-tier2';
+const payload = { session_id: sessionId, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' };
+const routed = run(kernel, [], payload);
+check(routed.status === 0, 'Tier 2 route persists successfully');
+
+const sessionDir = getSessionDir(ROOT, sessionId, payload);
+const workflowFile = path.join(sessionDir, 'workflow-run.json');
+const obligationFile = path.join(sessionDir, 'workflow-obligations.json');
+let workflow = readJson(workflowFile);
+let obligations = readJson(obligationFile);
+check(workflow.tier === 'tier2' && workflow.strategy === 'iterative-single', 'Tier 2 receives a preliminary iterative-single route');
+check(workflow.state === 'pending', 'selected Tier 2 workflow begins pending');
+check(obligations.phase === 'planning', 'Tier 2 immediately materializes a planning contract');
+check(obligations.obligations.map(item => item.id).join(',') === 'decompose,compose', 'planning starts with decompose then compose');
+check(obligations.requirements.length === 0, 'requirements begin empty instead of being invented by the router');
+check(obligations.workflowSelection.candidateStrategy === 'iterative-single', 'router topology is recorded only as candidate strategy');
+
+const prematureStart = run(controller, ['start', '--session-id', sessionId]);
+check(prematureStart.status !== 0, 'workflow start refuses to pretend planning is complete');
+workflow = readJson(workflowFile);
+check(workflow.state === 'pending', 'failed start leaves workflow pending');
+
+const mutationReminder = run(workflowGate, [], {
+  session_id: sessionId, cwd: ROOT, hook_event_name: 'PreToolUse',
+  tool_name: 'Write', tool_input: { file_path: path.join(ROOT, 'tmp-issue85.txt'), content: 'x' },
+});
+check(mutationReminder.status === 0, 'unresolved planning does not hard-block ordinary tools');
+
+const beforePlanStop = run(stopGate, [], { session_id: sessionId, cwd: ROOT, hook_event_name: 'Stop' });
+workflow = readJson(workflowFile);
+check(beforePlanStop.status === 0, 'Stop remains fail-open while planning is unresolved');
+check(workflow.state === 'pending', 'unresolved planning cannot silently become satisfied');
+check((workflow.unresolved || []).includes('decompose:pending'), 'decomposition gap is visible');
+check((workflow.unresolved || []).includes('compose:pending'), 'workflow-composition gap is visible');
+
+const requirements = JSON.stringify([
+  { id: 'req-fix', summary: 'Correct the checkout failure', acceptance: 'the failing scenario succeeds', suggestedSkills: ['tdd'] },
+  { id: 'req-regression', summary: 'Protect the behavior with a regression test', acceptance: 'the test fails before the fix and passes after it', suggestedSkills: ['tdd', 'verification-loop'] },
+]);
+const planned = run(controller, [
+  'plan', '--session-id', sessionId,
+  '--requirements-json', requirements,
+  '--strategy', 'iterative-single',
+  '--evidence', 'two dependent requirements fit a bounded single-agent test/fix/verify loop',
+]);
+check(planned.status === 0, 'requirements and workflow selection are recorded before execution');
+obligations = readJson(obligationFile);
+check(obligations.requirements.map(item => item.id).join(',') === 'req-fix,req-regression', 'requirement fragments are machine-readable');
+check(obligations.workflowSelection.disposition === 'confirmed', 'workflow choice is explicitly confirmed after decomposition');
+check(obligations.obligations.find(item => item.id === 'decompose').status === 'pass', 'decompose obligation resolves from requirement fragments');
+check(obligations.obligations.find(item => item.id === 'compose').status === 'pass', 'compose obligation resolves from workflow-selection evidence');
+
+const started = run(controller, ['start', '--session-id', sessionId]);
+check(started.status === 0, 'start activates the confirmed non-Fable workflow');
+workflow = readJson(workflowFile);
+obligations = readJson(obligationFile);
+check(workflow.state === 'running', 'confirmed workflow becomes running');
+check(obligations.phase === 'execution', 'planning contract advances to execution phase');
+check(obligations.obligations.map(item => item.id).join(',') === 'decompose,compose,execute,verify', 'execution adds execute/verify without losing planning evidence');
+
+check(run(controller, ['obligation', '--session-id', sessionId, '--obligation-id', 'execute', '--disposition', 'escaped', '--reason-code', 'workflow-uncovered-scope', '--scope', 'optional unrelated cleanup', '--evidence', 'outside requested bug-fix requirements']).status === 0,
+  'execution obligation accepts bounded evidence-backed escape');
+check(run(controller, ['obligation', '--session-id', sessionId, '--obligation-id', 'verify', '--disposition', 'escaped', '--reason-code', 'workflow-uncovered-scope', '--scope', 'tests', '--evidence', 'attempt']).status !== 0,
+  'verification obligation cannot be escaped');
+check(run(controller, ['obligation', '--session-id', sessionId, '--obligation-id', 'verify', '--disposition', 'blocked', '--reason-code', 'verification-environment-unavailable', '--evidence', 'fixture intentionally blocks verification']).status === 0,
+  'verification obligation can record explicit blocked evidence');
+
+const blockedStop = run(stopGate, [], { session_id: sessionId, cwd: ROOT, hook_event_name: 'Stop' });
+workflow = readJson(workflowFile);
+check(blockedStop.status === 0, 'blocked obligation still reminds without trapping Stop');
+check(workflow.state === 'running', 'blocked obligation keeps workflow unresolved rather than satisfied');
+check((workflow.unresolved || []).includes('verify:blocked'), 'blocked verification remains visible');
+
+check(run(controller, ['obligation', '--session-id', sessionId, '--obligation-id', 'verify', '--disposition', 'pass', '--evidence', 'npm test and focused regression passed']).status === 0,
+  'verification can later resolve to pass with evidence');
+check(run(statePersist, [], {
+  session_id: sessionId, cwd: ROOT, hook_event_name: 'PostToolUse',
+  tool_name: 'Bash', tool_input: { command: 'npm test' },
+  tool_response: { stdout: 'pass', stderr: '', exitCode: 0 },
+}).status === 0, 'objective verification milestone is observed after the earlier mutation');
+const resolvedStop = run(stopGate, [], { session_id: sessionId, cwd: ROOT, hook_event_name: 'Stop' });
+workflow = readJson(workflowFile);
+check(resolvedStop.status === 0, 'resolved workflow Stop remains fail-open');
+check(workflow.state === 'satisfied', 'planning + execution + verification allow satisfied');
+check((workflow.unresolved || []).length === 0, 'satisfied workflow has no unresolved obligations');
+
+const mismatchSession = 'issue85-replan';
+const mismatchPayload = { session_id: mismatchSession, cwd: ROOT, prompt: 'Fix this checkout bug and add a regression test.' };
+check(run(kernel, [], mismatchPayload).status === 0, 'second Tier 2 route persists for replan discriminator');
+const mismatchDir = getSessionDir(ROOT, mismatchSession, mismatchPayload);
+const mismatchPlan = run(controller, [
+  'plan', '--session-id', mismatchSession,
+  '--requirements-json', requirements,
+  '--strategy', 'fable-staged',
+  '--evidence', 'decomposition indicates dependent multi-stage work instead',
+]);
+check(mismatchPlan.status === 0, 'post-decomposition workflow can be recomposed through the router contract');
+const mismatchObligations = readJson(path.join(mismatchDir, 'workflow-obligations.json'));
+const mismatchWorkflow = readJson(path.join(mismatchDir, 'workflow-run.json'));
+check(mismatchObligations.workflowSelection.disposition === 'confirmed', 'recomposed workflow receives an explicit confirmed disposition');
+check(mismatchObligations.workflowSelection.requestedStrategy === 'fable-staged' &&
+  mismatchObligations.workflowSelection.confirmedStrategy === 'fable-staged',
+  'requested and router-confirmed post-decomposition strategy are preserved');
+check(mismatchWorkflow.pendingPlan?.strategy === 'fable-staged', 'recomposed plan becomes the pending execution contract');
+const mismatchStop = run(stopGate, [], { session_id: mismatchSession, cwd: ROOT, hook_event_name: 'Stop' });
+const mismatchAfterStop = readJson(path.join(mismatchDir, 'workflow-run.json'));
+check(mismatchStop.status === 0 && mismatchAfterStop.state === 'pending' &&
+  (mismatchAfterStop.unresolved || []).includes('execution:not-started'),
+  'recomposed workflow cannot become satisfied before its selected topology starts');
+const mismatchStart = run(controller, ['start', '--session-id', mismatchSession]);
+check(mismatchStart.status !== 0 && /workflow-stages\.json/.test(mismatchStart.stderr || ''),
+  'recomposed Fable topology proceeds to its native stage-contract requirement');
+check(run(workflowGate, [], {
+  session_id: mismatchSession, cwd: ROOT, hook_event_name: 'PreToolUse',
+  tool_name: 'Write', tool_input: { file_path: path.join(ROOT, 'tmp-replan.txt'), content: 'x' },
+}).status === 0, 'recomposed planning state still does not recreate a tool lock');
+
+const prohibitedSession = 'issue85-prohibited-recompose';
+const prohibitedPayload = { session_id: prohibitedSession, cwd: ROOT, prompt: 'Fix this checkout bug with a regression test. Do not use fable.' };
+check(run(kernel, [], prohibitedPayload).status === 0, 'prohibition fixture routes successfully');
+const prohibitedRequirements = JSON.stringify([
+  { id: 'req-safe', summary: 'Resolve the bug under the user constraints', acceptance: 'the fix is verified without prohibited topology' },
+]);
+const prohibitedPlan = run(controller, [
+  'plan', '--session-id', prohibitedSession,
+  '--requirements-json', prohibitedRequirements,
+  '--strategy', 'fable-staged',
+  '--evidence', 'candidate considered after decomposition',
+]);
+check(prohibitedPlan.status === 0, 'prohibited post-decomposition choice is evaluated by router policy');
+const prohibitedDir = getSessionDir(ROOT, prohibitedSession, prohibitedPayload);
+const prohibitedObligations = readJson(path.join(prohibitedDir, 'workflow-obligations.json'));
+check(prohibitedObligations.workflowSelection.disposition === 'blocked', 'original user prohibition survives recomposition');
+check(prohibitedObligations.obligations.find(item => item.id === 'decompose').status === 'pass' &&
+  prohibitedObligations.obligations.find(item => item.id === 'compose').status === 'blocked',
+  'requirements remain valid while only the prohibited workflow choice stays unresolved');
+
+const fableSession = 'issue85-fable';
+const fablePayload = { session_id: fableSession, cwd: ROOT, prompt: 'Refactor the entire authentication architecture in dependent stages.' };
+check(run(kernel, [], fablePayload).status === 0, 'Tier 3 Fable candidate persists successfully');
+const fableDir = getSessionDir(ROOT, fableSession, fablePayload);
+const fableWorkflow = readJson(path.join(fableDir, 'workflow-run.json'));
+const fablePlanning = readJson(path.join(fableDir, 'workflow-obligations.json'));
+check(fableWorkflow.strategy === 'fable-staged', 'Tier 3 keeps Fable as preliminary candidate');
+check(fablePlanning.obligations.map(item => item.id).join(',') === 'decompose,compose', 'Fable also requires requirements/workflow planning before stage execution');
+check(run(controller, ['start', '--session-id', fableSession]).status !== 0, 'Fable cannot enter stage execution before planning contract resolves');
+
+const tier1Session = 'issue85-tier1';
+const tier1Payload = { session_id: tier1Session, cwd: ROOT, prompt: 'Update one README typo' };
+check(run(kernel, [], tier1Payload).status === 0, 'Tier 1 route persists successfully');
+const tier1Dir = getSessionDir(ROOT, tier1Session, tier1Payload);
+const tier1WorkflowFile = path.join(tier1Dir, 'workflow-run.json');
+check(!fs.existsSync(path.join(tier1Dir, 'workflow-obligations.json')), 'clear bounded Tier 1 intent has no decomposition overhead');
+check(run(stopGate, [], { session_id: tier1Session, cwd: ROOT, hook_event_name: 'Stop' }).status === 0, 'Tier 1 direct Stop remains lightweight');
+const tier1Workflow = readJson(tier1WorkflowFile);
+check(tier1Workflow.strategy === 'direct-single' && tier1Workflow.state === 'satisfied', 'Tier 1 remains a minimal direct path');
+
+const runtimeSource = fs.readFileSync(path.join(ROOT, 'hooks/scripts/lib/workflow-runtime.js'), 'utf8');
+check(!runtimeSource.includes('.mutation-probes.lock'), '#190 mutation-probe lock remains retired');
+check(!runtimeSource.includes('budget-exhausted'), '#190 hard budget state remains retired');
+
+fs.rmSync(stateHome, { recursive: true, force: true });
+console.log('\n' + (failed === 0 ? 'PASS' : 'FAIL') + ': issue #85 requirements-first workflow contract (' + failed + ' failures)');
+process.exit(failed === 0 ? 0 : 1);

package/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.17.0
 ---
 
 # Harness Everything

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

@@ -44,7 +44,8 @@ function isHostNotificationPrompt(prompt) {
   return /^<task-notification[\s>][\s\S]*<\/task-notification>\s*$/i.test(text);
 }
 
-function persistWorkflow(plan, payload, prompt) {
+function persistWorkflow(contract, payload, prompt) {
+  const plan = contract && contract.workflowPlan;
   if (!payload || !(payload.session_id || payload.sessionId)) return null;
   const { runtime, hooksRoot } = loadRuntime();
   const context = runtime.loadWorkflow(payload);
@@ -83,6 +84,7 @@ function persistWorkflow(plan, payload, prompt) {
     verification: plan.verification,
     mutationIsolation: plan.mutationIsolation || { required: false },
     workflowPlan: plan,
+    taskShape: contract.taskShape || null,
     state: selected ? 'pending' : 'deferred',
     planningWarnings: plan.fallback?.disposition === 'none' ? [] : [...(plan.fallback?.reasonCodes || [])],
     runId: null,
@@ -94,6 +96,10 @@ function persistWorkflow(plan, payload, prompt) {
       hardBoundaries: ['rule-of-3-reflection', 'user-host-permission'],
     },
   };
+  if (selected && ['tier2', 'tier3'].includes(plan.tier)) {
+    const { initializePlanningContract } = require(path.join(hooksRoot, 'lib/workflow-obligations'));
+    initializePlanningContract(context, plan);
+  }
   const memoryCapability = issueMemoryCapability(context.workflow);
   runtime.saveWorkflow(context);
   return { ...context, hooksRoot, retained: false, memoryCapability };
@@ -115,7 +121,7 @@ function run(raw) {
   let persisted = null;
   let failure = null;
   try {
-    persisted = persistWorkflow(plan, payload, prompt);
+    persisted = persistWorkflow(result?.contract || null, payload, prompt);
     if (persisted?.retained && persisted.workflow) plan = persisted.workflow.workflowPlan;
   } catch (error) { failure = error; }
   if (hostNotification && !persisted?.workflow) {
@@ -146,7 +152,12 @@ function run(raw) {
     console.log('   - Memory write disposition: ' + (persisted.workflow.workflowPlan.memory?.write || 'none'));
     if (persisted.memoryCapability) console.log('   - Memory capability (single-use, workflow/session-bound): ' + persisted.memoryCapability);
     console.log('   - Stage specification: ' + path.join(persisted.sessionDir, 'workflow-stages.json'));
-    console.log('   - Enter/replan: node "' + controller + '" start --session-id "' + persisted.sessionId + '"');
+    if (plan.strategySelection === 'selected' && ['tier2', 'tier3'].includes(plan.tier)) {
+      console.log('   - Planning contract: ' + path.join(persisted.sessionDir, 'workflow-obligations.json'));
+      console.log('   - Requirements first: decompose intent into requirement fragments, then confirm the smallest sufficient workflow.');
+      console.log('   - Record plan: node "' + controller + '" plan --session-id "' + persisted.sessionId + '" --requirements-json "[{\\\"id\\\":\\\"req-1\\\",\\\"summary\\\":\\\"...\\\",\\\"acceptance\\\":\\\"...\\\"}]" --strategy "' + plan.strategy + '" --evidence "<why this workflow fits>"');
+    }
+    console.log('   - Enter selected workflow after planning: node "' + controller + '" start --session-id "' + persisted.sessionId + '"');
     console.log('   - Escape one declared stage: node "' + controller + '" escape --session-id "' + persisted.sessionId + '" --stage-id "<id>" --reason-code workflow-uncovered-scope --scope "<uncovered scope>" --evidence "<evidence>"');
   } else {
     console.log('   - Runtime state was not persisted; reminders may be less precise, but execution remains available.');

package/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,
+};