harness-everything 0.8.0 → 0.8.1

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

@@ -0,0 +1,102 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function git(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true, timeout: 5000 });
+  if (result.status !== 0) throw new Error('cannot verify Git worktree isolation');
+  return result.stdout.trim();
+}
+
+function canonical(value) {
+  const resolved = path.resolve(value);
+  // The JS resolver preserves Windows 8.3 spellings (RUNNER~1), while Git
+  // reports the long directory name. Native resolution gives one identity.
+  try { return fs.realpathSync.native(resolved); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const parent = path.dirname(resolved);
+    if (parent === resolved) return resolved;
+    return path.join(canonical(parent), path.basename(resolved));
+  }
+}
+
+function key(value) {
+  const result = canonical(value);
+  return process.platform === 'win32' ? result.toLowerCase() : result;
+}
+
+function within(root, target) {
+  const relative = path.relative(key(root), key(target));
+  return !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`);
+}
+
+function linkedWorktree(cwd, boundRoot) {
+  const common = canonical(git(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']));
+  const gitDir = canonical(git(cwd, ['rev-parse', '--absolute-git-dir']));
+  const boundCommon = canonical(git(boundRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir']));
+  const top = canonical(git(cwd, ['rev-parse', '--show-toplevel']));
+  if (key(common) === key(gitDir) || key(common) !== key(boundCommon)) return null;
+  const worktrees = git(boundRoot, ['worktree', 'list', '--porcelain', '-z']).split('\0');
+  return worktrees.some(field => field.startsWith('worktree ') && key(field.slice(9)) === key(top)) ? top : null;
+}
+
+// A conservative read subset, not a general shell sandbox.
+function classifyShell(command) {
+  const text = String(command || '').trim();
+  if (!text || /[;&|`\r\n<>$(){}\x00]/.test(text)) return 'mutation-or-unknown';
+  if (/^git\s+worktree\s+add\s+/i.test(text) && !/\s--(?:force|checkout|detach)(?:\s|=|$)/i.test(text)) return 'worktree-setup';
+  if (/\s(?:--(?:output|ext-diff|textconv|exec|pre|pre-glob|pager|open|batch|filters)|-[xoO])(?:\b|=)|\s-(?:exec|execdir|delete|fprint|fprintf)\b/i.test(text)) return 'mutation-or-unknown';
+  if (/^git\s+(?:status|rev-parse|diff|log|show|ls-files|check-ignore)(?:\s|$)/i.test(text) ||
+      /^git\s+branch\s+--show-current$/i.test(text) || /^git\s+worktree\s+list(?:\s|$)/i.test(text) ||
+      /^(?:pwd|ls|dir|cat|type|head|tail|wc|stat|rg|Get-Location|Get-ChildItem|Get-Content|Select-String|Test-Path)(?:\s|$)/i.test(text)) return 'read-only';
+  return 'mutation-or-unknown';
+}
+
+function inputOf(payload) { return payload?.tool_input ?? payload?.toolInput ?? payload?.input ?? {}; }
+function cwdOf(payload, root) {
+  const input = inputOf(payload);
+  return input.workdir || input.cwd || input.working_directory || input.workingDirectory ||
+    payload.cwd || payload.working_directory || payload.workingDirectory || root;
+}
+function commandOf(payload) {
+  const input = inputOf(payload);
+  return String(input.command || input.script || input.cmd || '');
+}
+function mutationPaths(payload) {
+  const input = inputOf(payload);
+  if ((payload.tool_name || payload.tool) === 'apply_patch') {
+    const patch = typeof input === 'string' ? input : input.patch || input.input || '';
+    return [...String(patch).matchAll(/^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)\r?$/gm)].map(match => match[1].trim());
+  }
+  return [input.file_path || input.filePath || input.path].filter(value => typeof value === 'string' && value.trim());
+}
+function assertTargets(payload, cwd, isolatedRoot) {
+  const targets = mutationPaths(payload);
+  if (!targets.length) throw new Error('mutation target is unknown; cannot verify worktree isolation');
+  for (const target of targets) {
+    const resolved = path.resolve(cwd, target);
+    if (!within(isolatedRoot, resolved) || within(path.join(isolatedRoot, '.git'), resolved)) {
+      throw new Error('mutation target escapes Git worktree isolation or modifies Git metadata');
+    }
+    let parent = path.dirname(resolved);
+    while (!fs.existsSync(parent)) parent = path.dirname(parent);
+    if (key(git(parent, ['rev-parse', '--show-toplevel'])) !== key(isolatedRoot)) throw new Error('mutation target belongs to a different repository');
+  }
+}
+function assertShellScope(command, cwd, isolatedRoot) {
+  if (/(?:^|[;&|\r\n])\s*(?:cd|chdir|pushd|Set-Location|Push-Location)\b/i.test(command)) {
+    throw new Error('use the shell tool working-directory field so isolation can be verified');
+  }
+  const tokens = command.match(/"[^"]*"|'[^']*'|[^\s;&|<>]+/g) || [];
+  for (const token of tokens.slice(1)) {
+    const value = token.replace(/^["']|["']$/g, '').replace(/^[A-Za-z-]+=/, '');
+    if ((path.isAbsolute(value) || /^\.\.[\\/]/.test(value)) && !within(isolatedRoot, path.resolve(cwd, value))) {
+      throw new Error('explicit shell path escapes Git worktree isolation');
+    }
+  }
+}
+
+module.exports = { canonical, key, within, linkedWorktree, classifyShell, inputOf, cwdOf, commandOf, mutationPaths, assertTargets, assertShellScope };

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

@@ -0,0 +1,102 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir, getSessionId, getStateRoot } = require('./harness-state');
+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}$/;
+
+function isMajorWorkflow(workflow) {
+  return Boolean(workflow && (workflow.mutationIsolation?.required || workflow.tier === 'tier3' || String(workflow.strategy || '').startsWith('fable-')));
+}
+
+function loadWorkflow(payload) {
+  const root = getWorkspaceRoot(payload);
+  const sessionId = getSessionId(payload);
+  const sessionDir = getSessionDir(root, sessionId, payload);
+  const file = path.join(sessionDir, 'workflow-run.json');
+  if (!fs.existsSync(file)) return { root, sessionId, sessionDir, file, workflow: null };
+  const workflow = readJson(file);
+  if (!workflow || !['deferred', 'satisfied', ...OPEN_STATES].includes(workflow.state)) {
+    throw new Error('recorded workflow is unreadable or invalid; repair its state before mutation/completion');
+  }
+  const strategies = ['direct-single', 'iterative-single', 'fable-staged', 'fable-parallel', 'fable-multi-agent-workspace'];
+  if (![1, 2].includes(workflow.schemaVersion) || workflow.sessionId !== sessionId ||
+      (workflow.state !== 'deferred' && !strategies.includes(workflow.strategy)) ||
+      (workflow.schemaVersion === 2 && (!workflow.workflowId || !workflow.workflowPlan ||
+        workflow.workflowPlan.strategy !== workflow.strategy || !Number.isInteger(workflow.revision) || workflow.revision < 0))) {
+    throw new Error('recorded workflow schema or session correlation is invalid');
+  }
+  return { root, sessionId, sessionDir, file, workflow };
+}
+
+function saveWorkflow(context) { atomicWriteJson(context.file, context.workflow); }
+
+function matchingRun(context) {
+  const { workflow, root, sessionId } = context;
+  if (!workflow || !SAFE_ID.test(workflow.runId || '') || !workflow.workflowId || !sessionId) return null;
+  const runRoot = path.join(getStateRoot(root), 'fable-runs', workflow.runId);
+  const run = readJson(path.join(runRoot, 'run.json'));
+  if (!run || run.runId !== workflow.runId || run.workflowId !== workflow.workflowId ||
+      run.sessionId !== sessionId || run.strategy !== workflow.strategy ||
+      !Number.isFinite(Date.parse(run.createdAt)) || !Array.isArray(run.stageIds) || !run.stageIds.length ||
+      new Set(run.stageIds).size !== run.stageIds.length || run.stageIds.some(id => !SAFE_ID.test(id))) return null;
+  return { runRoot, run };
+}
+
+function unresolvedStages(match, workflow) {
+  const unresolved = [];
+  const stages = [];
+  for (const stageId of match.run.stageIds) {
+    const contract = readJson(path.join(match.runRoot, 'contracts', `${stageId}.json`));
+    if (!contract || contract.stageId !== stageId || contract.runId !== match.run.runId ||
+        contract.planId !== match.run.planId || contract.sessionId !== match.run.sessionId) {
+      unresolved.push(`${stageId}:missing-or-uncorrelated`);
+      continue;
+    }
+    stages.push(contract);
+    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 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 ||
+        evidence.stageId !== stageId || evidence.sessionId !== contract.sessionId ||
+        evidence.checkCommand !== contract.checkCommand || !Number.isFinite(Date.parse(evidence.observedAt)) ||
+        evidence.workerId !== contract.workerId || !evidence.workerId || evidence.observedAt !== contract.verifiedAt) {
+      unresolved.push(`${stageId}:verification-unresolved`);
+    }
+  }
+  if (workflow.verification?.independent) {
+    const verifiers = stages.filter(stage => stage.agent === 'fable-verifier' && stage.writeSet?.length === 0);
+    const workers = stages.filter(stage => stage.agent !== 'fable-verifier').map(stage => stage.workerId).filter(Boolean);
+    const latestCheck = Math.max(0, ...stages.filter(stage => stage.agent !== 'fable-verifier').map(stage => Date.parse(stage.verifiedAt) || 0));
+    if (!verifiers.some(stage => stage.workerId && !workers.includes(stage.workerId) && stage.status === 'pass' &&
+        Date.parse(stage.verifiedAt) >= Math.max(workflow.lastMutationAt || 0, latestCheck) &&
+        match.run.stageIds.filter(id => id !== stage.stageId).every(id => stage.dependsOn?.includes(id)))) {
+      unresolved.push('independent-verifier-missing');
+    }
+  }
+  return unresolved;
+}
+
+function readHookInput(decide) {
+  let input = '';
+  let finished = false;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    clearTimeout(timeout);
+    try { decide(input.trim() ? JSON.parse(input) : null); }
+    catch (error) { console.error(`[Workflow Gate] ${error.message}`); process.exitCode = 2; }
+  };
+  const timeout = setTimeout(finish, 500);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { input += chunk; });
+  process.stdin.on('end', finish);
+  process.stdin.on('error', finish);
+}
+
+module.exports = { OPEN_STATES, SAFE_ID, isMajorWorkflow, loadWorkflow, saveWorkflow, matchingRun, unresolvedStages, readHookInput };

package/plugins/harness-everything/hooks/scripts/state-persist.js

@@ -83,6 +83,7 @@ function processState(payload) {
         const command = (payload.tool_input && payload.tool_input.command) || '';
         if (VERIFY_COMMAND_RE.test(command)) {
           state.lastVerifyAt = Date.now();
+          state.lastVerifyExitCode = exitCode ?? null;
         }
       }
 

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

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadWorkflow, saveWorkflow, matchingRun, OPEN_STATES } = require('./lib/workflow-runtime');
+const { getWorkspaceRoot, readCurrentSession } = require('./lib/harness-state');
+const { atomicWriteJson, readJson } = require('./lib/fable-contracts');
+
+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']]);
+  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]);
+    args[key] = argv[++i];
+  }
+  return args;
+}
+
+function consumer() {
+  for (const relative of ['../../fable-mode/scripts/workflow-plan-consumer.js', '../../skills/fable-mode/scripts/workflow-plan-consumer.js']) {
+    const file = path.resolve(__dirname, relative);
+    if (fs.existsSync(file)) return require(file);
+  }
+  throw new Error('Fable consumer unavailable');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const sessionId = args.sessionId || readCurrentSession(getWorkspaceRoot());
+  if (!sessionId) throw new Error('no active Harness session; pass --session-id explicitly');
+  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 === '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 max = workflow.workflowPlan.limits?.maxRevisionRounds ?? 2;
+    if (workflow.revision > max) throw new Error('replan budget exhausted; workflow remains blocked');
+    const plan = workflow.pendingPlan || workflow.workflowPlan;
+    if (!String(plan.strategy || '').startsWith('fable-')) {
+      workflow.revision++;
+      workflow.state = 'running';
+      delete workflow.blockReason;
+      saveWorkflow(context);
+      process.stdout.write(JSON.stringify({ state: workflow.state, workflowId: workflow.workflowId, revision: workflow.revision }) + '\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');
+    if (plan.verification?.independent && !stages.some(stage => stage.agent === 'fable-verifier' && stage.writeSet?.length === 0 &&
+        stages.filter(other => other !== stage).every(other => stage.dependsOn?.includes(other.stageId)))) {
+      throw new Error('independent verification requires a read-only fable-verifier stage depending on all other stages');
+    }
+    const run = consumer().prepareRun({
+      routerContract: { workflowPlan: plan }, stages, workspaceRoot: context.root,
+      sessionId, workflowId: workflow.workflowId,
+    });
+    workflow.workflowPlan = plan;
+    workflow.strategy = plan.strategy;
+    workflow.tier = plan.tier;
+    workflow.verification = plan.verification;
+    workflow.mutationIsolation = plan.mutationIsolation || workflow.mutationIsolation;
+    workflow.runId = run.runId;
+    workflow.revision++;
+    workflow.state = 'running';
+    workflow.escapes = [];
+    delete workflow.pendingPlan;
+    delete workflow.blockReason;
+  } else if (args.command === 'escape') {
+    if (!ALLOWED_ESCAPE_REASONS.has(args.reasonCode)) throw new Error('generic simple/routine/already-clear reasons are intentionally rejected');
+    if (!args.scope?.trim()) throw new Error('--scope is required');
+    if (!args.evidence?.trim()) throw new Error('--evidence is required');
+    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');
+    const contract = readJson(path.join(match.runRoot, 'contracts', args.stageId + '.json'));
+    if (contract?.agent === 'fable-verifier') throw new Error('independent verification cannot be escaped; record BLOCKED when unavailable');
+    const disposition = {
+      status: 'escaped', stageId: args.stageId, runId: match.run.runId,
+      reasonCode: args.reasonCode, uncoveredScope: args.scope.trim(), evidence: args.evidence.trim(), recordedAt: new Date().toISOString(),
+    };
+    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: workflow-disposition.js <start|escape|block> --session-id <id> [--stage-id <id> --reason-code <reason> --scope <scope> --evidence <evidence>]');
+  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-gate.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { loadWorkflow, saveWorkflow, isMajorWorkflow, matchingRun, readHookInput } = require('./lib/workflow-runtime');
+const { key, classifyShell, cwdOf, commandOf, mutationPaths, linkedWorktree, assertTargets, assertShellScope } = require('./lib/workflow-isolation');
+
+const DIRECT = new Set(['Edit', 'Write', 'apply_patch']);
+const SHELL = new Set(['Bash', 'PowerShell', 'exec_command']);
+
+function isController(command, cwd) {
+  // One trusted local executable, literal arguments, no shell evaluation.
+  if (/[;&|`\r\n<>$(){}]/.test(command)) return false;
+  const match = command.match(/^node\s+(?:"([^"]+)"|'([^']+)'|(\S+))\s+(start|escape|block)\b/);
+  return Boolean(match && key(path.resolve(cwd, match[1] || match[2] || match[3])) === key(path.join(__dirname, 'workflow-disposition.js')));
+}
+
+function decide(payload) {
+  if (!payload) return;
+  const tool = payload.tool_name || payload.tool;
+  if (!DIRECT.has(tool) && !SHELL.has(tool)) return;
+  const context = loadWorkflow(payload);
+  const { workflow, root, sessionDir } = context;
+  if (!workflow || workflow.state === 'deferred') return;
+  const cwd = cwdOf(payload, root);
+  const command = commandOf(payload);
+  const commandClass = SHELL.has(tool) ? classifyShell(command) : 'direct-mutation';
+  if (commandClass === 'read-only' || commandClass === 'worktree-setup') return;
+  if (SHELL.has(tool) && isController(command, cwd)) return;
+  // Only the stage specification is allowed before run entry. Other runtime
+  // state, including workflow-run.json, cannot use this bootstrap exception.
+  const targets = DIRECT.has(tool) ? mutationPaths(payload) : [];
+  const spec = path.join(sessionDir, 'workflow-stages.json');
+  const specStat = fs.existsSync(spec) ? fs.lstatSync(spec) : null;
+  if ((!specStat || (specStat.isFile() && !specStat.isSymbolicLink() && specStat.nlink === 1)) &&
+      targets.length && targets.every(target => key(path.resolve(cwd, target)) === key(spec))) return;
+  if (['blocked', 'failed'].includes(workflow.state)) throw new Error('workflow is BLOCKED; replan through the controller before mutation');
+  if (isMajorWorkflow(workflow)) {
+    const isolatedRoot = linkedWorktree(cwd, root);
+    if (!isolatedRoot) throw new Error('Git worktree isolation is required before mutation. Enter a linked worktree; unavailable isolation means BLOCKED, never in-place fallback.');
+    if (DIRECT.has(tool)) assertTargets(payload, cwd, isolatedRoot);
+    else assertShellScope(command, cwd, isolatedRoot);
+  }
+  if (workflow.state === 'satisfied') throw new Error('workflow is already satisfied; submit a new task before further mutation');
+  if (String(workflow.strategy || '').startsWith('fable-') && !matchingRun(context)) {
+    throw new Error('selected Fable workflow has no correlated run. Write workflow-stages.json at the displayed session path, then use workflow-disposition.js start.');
+  }
+  workflow.lastMutationAt = Date.now();
+  saveWorkflow(context);
+}
+
+readHookInput(decide);

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { readJson } = require('./lib/fable-contracts');
+const { loadWorkflow, saveWorkflow, matchingRun, unresolvedStages, readHookInput } = require('./lib/workflow-runtime');
+
+function decide(payload) {
+  if (!payload) return;
+  const context = loadWorkflow(payload);
+  const { workflow, sessionDir } = context;
+  if (!workflow || ['deferred', 'satisfied'].includes(workflow.state)) return;
+  if (workflow.state === 'blocked') {
+    console.error('[Workflow Completion Gate] BLOCKED: report the unresolved work; completion has not been verified.');
+    return;
+  }
+  let unresolved = [];
+  if (String(workflow.strategy || '').startsWith('fable-')) {
+    const match = matchingRun(context);
+    unresolved = match ? unresolvedStages(match, workflow) : ['correlated-run-missing'];
+  } else {
+    const handoff = readJson(path.join(sessionDir, 'handoff-state.json'));
+    const lastEdit = Math.max(workflow.lastMutationAt || 0, handoff?.lastEditAt || 0);
+    if (lastEdit && ((handoff?.lastVerifyAt || 0) < lastEdit || handoff?.lastVerifyExitCode !== 0)) unresolved = ['verification-after-edit-missing'];
+  }
+  if (unresolved.length) {
+    workflow.unresolved = unresolved;
+    if (payload.stop_hook_active) {
+      // Do not loop forever or pretend the retry satisfied the contract.
+      workflow.state = 'blocked';
+      workflow.blockReason = 'unresolved-stop-retry';
+      saveWorkflow(context);
+      console.error('[Workflow Completion Gate] BLOCKED: ' + unresolved.join(', ') + '. Report the blocker; this is not completion.');
+      return;
+    }
+    saveWorkflow(context);
+    throw new Error('Cannot complete: unresolved workflow obligations: ' + unresolved.join(', '));
+  }
+  workflow.state = 'satisfied';
+  workflow.resolvedAt = new Date().toISOString();
+  workflow.unresolved = [];
+  saveWorkflow(context);
+}
+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.8.0",
+  "version": "0.8.1",
   "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

@@ -1,6 +1,5 @@
-// Prompt-injection-only guidance for platforms with no hook/execution
-// mechanism (Cursor, Copilot, Codex, Continue, Hermes). Single source of
-// truth for the advisory block.
+// Prompt-injection guidance for integration paths where Harness cannot prove
+// lifecycle-hook enforcement. Single source of truth for advisory blocks.
 const fs = require('fs');
 const path = require('path');
 
@@ -8,34 +7,36 @@ const MARKER = "Harness OS Guidance (Advisory)";
 
 const advisoryInstructions = [
   `\n# ${MARKER}`,
-  `This file is advisory only - this platform has no hook/execution mechanism to`,
-  `enforce it mechanically (unlike Claude Code's hook-based circuit breaker). Treat`,
-  `these as strong defaults, not guarantees.`,
+  `This surface cannot be assumed to mechanically enforce every Harness lifecycle transition.`,
+  `Treat the workflow contract below as required agent behavior, while keeping enforcement`,
+  `claims bounded by the host's verified capabilities.`,
   ``,
-  `## 🚦 MANDATORY ENTRY TRIAGE & ROUTING (ALWAYS RUN FIRST)`,
-  `Every time you receive a new software/project prompt, you MUST load the \`harness-everything\` skill and immediately do the following:`,
-  `1. Run \`npx github:dyphn1/Harness-everything next "<Brief summary of user's prompt>"\` (this prints the same routing recommendation kernel-router.js produces - it works from any directory and does not depend on where a local copy of the skill was installed). If the terminal is not available yet, apply the same routing contract from the loaded \`harness-everything\` skill instead of skipping this step.`,
-  `2. For EVERY suggested skill, resolve and read its complete \`SKILL.md\` entry before deciding to skip it. Evaluate \`USE FOR\`, \`DO NOT USE FOR\`, workflow/basic flow, and hard rules against the task. If the entry explicitly requires another document to decide applicability, read that required material too. Do not reject a suggestion from only its name, description, router summary, or because the task seems routine/common.`,
-  `3. After that evaluation, execution is advisory: use, combine, reorder, or skip skills as justified. Using one suggestion does not waive read-before-skip for the others. If a suggested skill cannot be resolved/read, mark it unresolved/unavailable instead of silently skipping it.`,
-  `4. Output a clear routing checkpoint near the beginning of your response/update:`,
+  `## 🚦 MANDATORY ENTRY TRIAGE & WORKFLOW ROUTING`,
+  `For every software/project prompt, load the \`harness-everything\` skill and establish the routing contract before mutation:`,
+  `1. Run \`npx github:dyphn1/Harness-everything next "<Brief summary of user's prompt>"\`. If terminal execution is unavailable, apply the same contract from the skill instead of skipping routing.`,
+  `2. For EVERY suggested skill, read its complete \`SKILL.md\` entry and resolve applicability from \`USE FOR\`, \`DO NOT USE FOR\`, workflow/basic flow, and hard rules. A name, description, router summary, or "routine/simple/already clear" judgement is not enough to omit it.`,
+  `3. The selected workflow topology is mandatory once applicable. Execute it to resolution; choose tools, reasoning, implementation technique, and decomposition freely inside it. Do not replace it with a direct path because you believe you can solve the task without the workflow.`,
+  `4. If the selected workflow genuinely cannot cover part of the task, record an explicit escape for the uncovered scope with evidence. Covered obligations remain mandatory. Host-capability loss must be surfaced, not silently converted into optional execution.`,
+  `5. Surface a compact checkpoint near the first progress update:`,
   `   \`\`\`markdown`,
   `   ## 🚦 Harness OS Routing Checkpoint`,
-  `   - **Active Tier**: Tier 1 (Trivial) | Tier 2 (Standard) | Tier 3 (Macro)`,
-  `   - **Rationale**: <1-sentence rationale from the router output>`,
+  `   - **Active Tier**: Tier 1 | Tier 2 | Tier 3 | unclassified`,
+  `   - **Strategy**: <selected/deferred strategy>`,
+  `   - **Workflow State**: <active | deferred | blocked | escaped>`,
   `   - **Required Invariants**: <router invariants>`,
-  `   - **Suggested Skills**: <deduplicated router suggestions or none>`,
-  `   - **Suggestion Evaluation**: <evaluated before skip | pending | unresolved/unavailable>`,
-  `   - **Disposition**: <skills used, or skipped all after evaluation with a brief flow-grounded reason>`,
+  `   - **Suggested Skills**: <deduplicated suggestions or none>`,
+  `   - **Applicability**: <use | not-applicable + reason | unresolved/unavailable>`,
+  `   - **Escape**: <none | reason + uncovered scope + evidence>`,
   `   \`\`\``,
   ``,
-  `## 🤖 COGNITIVE COMPLIANCE (NO SILENT DEGRADES FOR NEW FEATURES)`,
-  `- **Newly Added Features / Extensions**: Do not silently collapse a task that introduces new logic, a new API endpoint, or a new file/module into a trivial direct-edit path. Route it first and justify the tier from task evidence.`,
-  `- **Tier 2 / Tier 3 Suggestions**: There is NO universal TODO/TDD/Fable sequence. Router suggestions are mandatory to evaluate by reading their skill entry, but optional to execute after that evaluation. Choose the smallest applicable set.`,
-  `- **Pre-Completion Verification Gate**: Before telling the human the task is done, run \`npx github:dyphn1/Harness-everything verify\` in the project root. If it exits non-zero, fix the failures and run it again before declaring completion. On Claude Code this same check can be mechanically enforced by a stop hook; here nothing blocks you from skipping it, so treat it as a real requirement, not a suggestion.`,
-  `- **Memory Summarization (Self-Evolve)**: When the task produces a reusable verified lesson, use the \`self-evolve\` flow to persist it; do not manufacture memory for routine work.`,
-  `- **Environment Discovery**: Discover the environment (OS, shell, package manager) before running commands - don't assume.`,
-  `- **Rule of 3**: If the same error repeats 3 times in a row, STOP retrying. Explain what's failing and use a fresh diagnosis / zoom-out instead of continuing to guess.`,
-  `- **Prefer Editing**: Prefer editing over rewriting; commit logically complete chunks rather than one giant diff.`,
+  `## 🤖 COGNITIVE COMPLIANCE`,
+  `- **No universal skill pipeline**: do not force every task through TODO/TDD/Fable. The router selects the smallest sufficient topology; suggested skills are resolved for applicability.`,
+  `- **Applicable skill flow**: reading a skill is not permission to discard it when its workflow actually applies.`,
+  `- **Pre-completion verification**: before declaring done, run \`npx github:dyphn1/Harness-everything verify\` in the project root and fix failures. An instruction-only host may not block you mechanically, but the requirement remains part of the contract.`,
+  `- **Rule of 3**: after 3 same-signature failures, stop micro-retrying and use a fresh diagnosis / zoom-out.`,
+  `- **Environment discovery**: discover OS, shell, package manager/runtime, and host capability before relying on them.`,
+  `- **Memory / self-evolve**: persist only verified reusable lessons; use escape/replan/recovery evidence to improve workflow coverage rather than bypassing the active workflow.`,
+  `- **Prefer editing**: prefer targeted edits and logically complete commits over broad rewrites.`,
   ``
 ].join('\n');
 
@@ -70,30 +71,27 @@ function injectAdvisoryText(targetFile, header, label) {
 function removeAdvisoryText(targetFile) {
   if (!fs.existsSync(targetFile)) return;
   try {
-    let content = fs.readFileSync(targetFile, 'utf8');
+    const content = fs.readFileSync(targetFile, 'utf8');
     const markerIndex = content.indexOf(MARKER);
-    if (markerIndex !== -1) {
-      let cleanContent = content;
-      const hashMarkerIndex = content.lastIndexOf('#', markerIndex);
-      if (hashMarkerIndex !== -1) cleanContent = content.substring(0, hashMarkerIndex).trim() + '\n';
-      else cleanContent = content.substring(0, markerIndex).trim() + '\n';
+    if (markerIndex === -1) return;
+    let cleanContent = content;
+    const hashMarkerIndex = content.lastIndexOf('#', markerIndex);
+    if (hashMarkerIndex !== -1) cleanContent = content.substring(0, hashMarkerIndex).trim() + '\n';
+    else cleanContent = content.substring(0, markerIndex).trim() + '\n';
 
-      const lines = cleanContent.trim().split('\n').map(l => l.trim()).filter(l => l !== '');
-      if (lines.length === 0 || (lines.length === 1 && (lines[0] === '# Cursor Project Rules' || lines[0] === '# AGENTS.md' || lines[0] === '# Copilot Instructions' || lines[0] === '# .hermes.md'))) {
-        fs.unlinkSync(targetFile);
-        console.log(`  ✅ Removed empty advisory file: ${targetFile}`);
-      } else {
-        fs.writeFileSync(targetFile, cleanContent.trim() + '\n', 'utf8');
-        console.log(`  ✅ Removed Harness guidance from: ${targetFile}`);
-      }
+    const lines = cleanContent.trim().split('\n').map(l => l.trim()).filter(Boolean);
+    if (lines.length === 0 || (lines.length === 1 && ['# Cursor Project Rules', '# AGENTS.md', '# Copilot Instructions', '# .hermes.md'].includes(lines[0]))) {
+      fs.unlinkSync(targetFile);
+      console.log(`  ✅ Removed empty advisory file: ${targetFile}`);
+    } else {
+      fs.writeFileSync(targetFile, cleanContent.trim() + '\n', 'utf8');
+      console.log(`  ✅ Removed Harness guidance from: ${targetFile}`);
     }
   } catch (e) {
     console.warn(`  ⚠️ Error removing advisory text from ${targetFile}: ${e.message}`);
   }
 }
 
-// Continue gets a dedicated rule file. If a user already owns that exact
-// path, do not replace it just because Harness chose the same filename.
 function installContinueRule(targetFile, label) {
   const dir = path.dirname(targetFile);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -103,7 +101,7 @@ function installContinueRule(targetFile, label) {
     `---`,
     `name: Harness OS Guidance`,
     `alwaysApply: true`,
-    `description: "Harness OS routing, circuit-breaker awareness, and environment-discovery guidance (advisory only on Continue - no hook mechanism)"`,
+    `description: "Harness OS routing and workflow guidance (instruction-governed on Continue unless a lifecycle mechanism is independently verified)"`,
     `---`,
     advisoryInstructions.replace(/^\n/, '')
   ].join('\n');
@@ -139,25 +137,24 @@ function buildCopilotGlobalContent() {
 function buildCodexGlobalContent() {
   return [
     `---`,
-    `description: "Harness OS Guidance - Global custom agent for orchestrating multi-agent workflows"`,
+    `description: "Harness OS Guidance - Global custom agent for orchestrating software workflows"`,
     `name: "Harness"`,
     `user-invocable: true`,
     `---`,
     `# AGENTS.md`,
     ``,
     `# ${MARKER}`,
-    `This file is advisory only - this platform has no hook/execution mechanism to`,
-    `enforce it mechanically. Treat these as strong defaults, not guarantees.`,
+    `This instruction surface cannot be assumed to provide hard lifecycle blocking.`,
     ``,
-    `- Discover the environment (OS, shell, package manager) before running commands - don't assume.`,
+    `- 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 EVERY suggested skill, read its complete \`SKILL.md\` entry/basic flow before skipping it. Evaluate \`USE FOR\`, \`DO NOT USE FOR\`, workflow, and hard rules; do not skip from the name/description/router summary alone.`,
-    `- Suggested-skill execution remains optional after evaluation. Using one suggestion does not waive evaluation of the other omitted suggestions; unreadable suggestions are unresolved/unavailable, not silently skipped.`,
-    `- Do not impose a universal TODO/TDD/Fable sequence. Choose the smallest applicable skill set after evaluation.`,
-    `- Before declaring a task done, run \`npx github:dyphn1/Harness-everything verify\` and fix any failures`,
-    `  it reports - nothing here blocks you from skipping this, so treat it as a real requirement.`,
-    `- If the same error repeats 3 times in a row, STOP retrying and use a fresh diagnosis / zoom-out.`,
-    `- Prefer editing over rewriting; commit logically complete chunks rather than one giant diff.`,
+    `- Read every suggested skill's complete \`SKILL.md\` entry before resolving applicability; do not omit it from metadata or confidence alone.`,
+    `- Execute the selected workflow topology to resolution. The model controls HOW inside the topology, not WHETHER the selected topology exists.`,
+    `- Do not impose a universal TODO/TDD/Fable sequence; use the smallest selected topology plus applicable skills.`,
+    `- Escape only for genuinely uncovered workflow scope and record reason + scope + evidence.`,
+    `- Before declaring done, run \`npx github:dyphn1/Harness-everything verify\` and fix failures.`,
+    `- After 3 same-signature failures, stop retrying and use a fresh diagnosis / zoom-out.`,
+    `- Prefer targeted edits and logically complete commits.`,
     ``
   ].join('\n');
 }
@@ -173,4 +170,4 @@ module.exports = {
   removeContinueRule,
   buildCopilotGlobalContent,
   buildCodexGlobalContent,
-};
+};

package/plugins/harness-everything/skills/fable-mode/CONTRACT-FORMAT.md

@@ -59,7 +59,9 @@ Rules:
 
 ## Workflow-plan consumer
 
-Before dispatch, write the router contract and stage array to files and run:
+For a session with an active mandatory workflow, write the stage array to the router-displayed `workflow-stages.json` path and invoke its `workflow-disposition.js start --session-id <id>` command. This binds the run to the active `workflowId` and bound workspace even after entering a linked worktree. Every required stage needs an objective check, and an independent plan needs a read-only `fable-verifier` stage depending on all other stages. Stage results need observed worker identities and numeric exit codes; missing metadata is blocked/degraded, not success.
+
+For standalone use without an active session contract, write the router contract and stage array to files and run:
 
 ```bash
 node fable-mode/scripts/workflow-plan-consumer.js \

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

@@ -4,7 +4,7 @@ description: "Stage large, multi-source or multi-session tasks through a written
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.8.1
 ---
 
 # Fable Mode (v3)

package/plugins/harness-everything/skills/fable-mode/execution-guardrails/SKILL.md

@@ -7,7 +7,7 @@ description: >-
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.8.1
 ---
 
 # Execution Guardrails