harness-everything 0.3.6 → 0.4.0

package/harness-everything/schemas/router-workflow-plan.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dyphn1/Harness-everything/harness-everything/schemas/router-workflow-plan.schema.json",
+  "title": "Harness Router Workflow Plan",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "routingStatus",
+    "tier",
+    "strategy",
+    "strategySelection",
+    "patterns",
+    "requiredInvariants",
+    "suggestedSkills",
+    "actionGate",
+    "limits",
+    "parallelism",
+    "workspace",
+    "memory",
+    "verification",
+    "ensemble",
+    "modelSelection",
+    "fallback",
+    "reasonCodes"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "routingStatus": { "enum": ["ok", "degraded"] },
+    "tier": { "enum": ["tier1", "tier2", "tier3", "unclassified"] },
+    "strategy": {
+      "enum": ["direct-single", "iterative-single", "fable-staged", "fable-parallel", "fable-multi-agent-workspace", null]
+    },
+    "strategySelection": { "enum": ["shadow", "selected", "deferred"] },
+    "patterns": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "requiredInvariants": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "suggestedSkills": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "actionGate": {
+      "type": "object",
+      "required": ["required", "reasonCodes", "approver", "disposition"],
+      "additionalProperties": false,
+      "properties": {
+        "required": { "type": "boolean" },
+        "reasonCodes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "approver": { "enum": ["rule-or-human", null] },
+        "disposition": { "enum": ["executed", "rejected", "pending-approval", null] }
+      }
+    },
+    "limits": {
+      "type": "object",
+      "required": ["maxIterations", "maxRevisionRounds", "maxWorkers"],
+      "additionalProperties": false,
+      "properties": {
+        "maxIterations": { "type": ["integer", "null"], "minimum": 1 },
+        "maxRevisionRounds": { "type": "integer", "minimum": 0, "maximum": 2 },
+        "maxWorkers": { "enum": ["fable-orchestrator-cap"] }
+      }
+    },
+    "parallelism": {
+      "type": "object",
+      "required": ["allowed", "requires", "reasonCodes"],
+      "additionalProperties": false,
+      "properties": {
+        "allowed": { "type": ["boolean", "null"] },
+        "requires": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "reasonCodes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "required": ["required", "reasonCodes"],
+      "additionalProperties": false,
+      "properties": {
+        "required": { "type": ["boolean", "null"] },
+        "reasonCodes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      }
+    },
+    "memory": {
+      "type": "object",
+      "required": ["read", "scope", "write"],
+      "additionalProperties": false,
+      "properties": {
+        "read": { "enum": ["workspace-index", "none", null] },
+        "scope": { "enum": ["task-relevant-only"] },
+        "write": { "enum": ["none", "propose", "persist-via-self-evolve"] }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "required": ["mode", "independent"],
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["verify-before-claim", "objective", "cold-verifier"] },
+        "independent": { "type": ["boolean", "null"] }
+      }
+    },
+    "ensemble": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["maxCandidates", "diversity", "synthesis", "verifier", "reasonCodes"],
+          "additionalProperties": false,
+          "properties": {
+            "maxCandidates": { "type": "integer", "minimum": 2, "maximum": 4 },
+            "diversity": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": { "enum": ["model", "prompt", "evidence"] }
+            },
+            "synthesis": { "const": "preserve-disagreement" },
+            "verifier": { "const": "independent" },
+            "reasonCodes": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "uniqueItems": true
+            }
+          }
+        }
+      ]
+    },
+    "modelSelection": {
+      "type": "object",
+      "required": ["requested", "policy"],
+      "additionalProperties": false,
+      "properties": {
+        "requested": { "enum": ["haiku", "sonnet", "opus", null] },
+        "policy": { "enum": ["defer-to-fable-selector"] }
+      }
+    },
+    "fallback": {
+      "type": "object",
+      "required": ["onMissingSubagents", "disposition", "mode", "reasonCodes"],
+      "additionalProperties": false,
+      "properties": {
+        "onMissingSubagents": { "enum": ["visible-inline-or-stop"] },
+        "disposition": { "enum": ["none", "reduced", "blocked"] },
+        "mode": { "enum": ["none", "inline", "serialized", "blocked"] },
+        "reasonCodes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      }
+    },
+    "reasonCodes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    }
+  },
+  "additionalProperties": false
+}

package/harness-everything/scripts/bootstrap.js

@@ -3,6 +3,7 @@ const fs = require('fs');
 const path = require('path');
 const {
   getWorkspaceRoot,
+  getSessionId,
   getSessionDir,
   writeCurrentSession,
   pruneStaleSessions,
@@ -24,9 +25,9 @@ if (!process.stdin.isTTY) {
     // No payload piped in, or invalid JSON - fall back to 'default'.
   }
 }
-const sessionId = payload && payload.session_id;
+const sessionId = getSessionId(payload);
 
-const root = getWorkspaceRoot();
+const root = getWorkspaceRoot(payload);
 
 // Guard: only materialize state in a workspace that actually has Harness
 // installed. Without this, running a Claude session in any random folder
@@ -110,7 +111,7 @@ if (fs.existsSync(subagentScopeFile)) {
 try {
   const MARKER = 'Harness OS Guidance (Advisory)';
   const HOOK_ID = 'harness:pre:bootstrap';
-  const workspaceRoot = getWorkspaceRoot();
+  const workspaceRoot = getWorkspaceRoot(payload);
   const contains = (p, needle) => {
     try { return fs.readFileSync(p, 'utf8').includes(needle); } catch (e) { return false; }
   };
@@ -157,7 +158,15 @@ try {
     missing.push('AGENTS.md (Codex)');
   }
 
-  if (missing.length > 0 && path.resolve(workspaceRoot) !== path.resolve(__dirname, '..', '..')) {
+  // Identity, not path: __dirname/../.. is the INSTALLED copy's root, so an
+  // npx/global install auditing the harness checkout itself compares two
+  // different paths and wrongly advises a repair that self-heal then skips
+  // (issue #40). Required lazily so a missing lib can never break session start.
+  const { isHarnessRepo } = require('../../scripts/lib/workspace');
+  const auditingSelf = isHarnessRepo(workspaceRoot)
+    || path.resolve(workspaceRoot) === path.resolve(__dirname, '..', '..');
+
+  if (missing.length > 0 && !auditingSelf) {
     console.log(`\n[Self-Heal] Missing integration touchpoints: ${missing.join(', ')}`);
     console.log(`[Self-Heal] Repair (idempotent): node "${path.join(__dirname, 'self-heal.js')}"`);
   }

package/harness-everything/scripts/ensemble-policy.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const ENSEMBLE_MAX_CANDIDATES = 3;
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function detectEnsembleTaskSignals(prompt) {
+  const text = String(prompt || '');
+  const comparableOutput = /\b(?:choice|choose|decision|decide|ranking|rank|ranked|verdict|recommendation|recommend|compare alternatives?|compare approaches?|which (?:option|approach|design)|select between|trade[- ]offs?)\b/i.test(text) ||
+    /(?:選擇|決策|排名|判定|建議|比較方案|比較方法|取捨)/.test(text);
+  const explicitDisagreement = /\b(?:disagreement|dissent|minority (?:view|position)|competing (?:answers|positions|approaches)|preserve disagreement)\b/i.test(text) ||
+    /(?:分歧|不同意見|少數意見|競爭方案)/.test(text);
+  const creativeGeneration = /\b(?:creative|brainstorm|story|poem|fiction|slogan|tagline|copywriting|marketing copy|logo|illustration|artwork|lyrics?|name ideas?|generate ideas?)\b/i.test(text) ||
+    /(?:創意|腦力激盪|故事|詩|標語|文案|插畫|歌詞|命名)/.test(text);
+  const mechanicalWork = /\b(?:mechanical|bulk rename|mass rename|rename all|replace all|reformat|format all|lint[- ]fix|sort imports?|codemod|repetitive edits?|generated files?|migrate all identifiers?)\b/i.test(text) ||
+    /(?:機械式|批次重新命名|全部取代|大量重複修改|格式化全部)/.test(text);
+  const highStakes = /\b(?:high[- ]stakes|safety[- ]critical|security[- ]critical|critical decision|material risk)\b/i.test(text) ||
+    /(?:高風險|高利害|關鍵決策)/.test(text);
+  return {
+    comparableOutput,
+    explicitDisagreement,
+    creativeGeneration,
+    mechanicalWork,
+    highStakes,
+  };
+}
+
+function applyEnsemblePolicy(contract, prompt) {
+  if (!contract || typeof contract !== 'object' || !contract.workflowPlan || !contract.taskShape) return contract;
+  const plan = contract.workflowPlan;
+  const shape = contract.taskShape;
+  const explicit = shape.explicitRequest || {};
+  const prohibitions = Array.isArray(explicit.prohibitions) ? explicit.prohibitions : [];
+  const signals = detectEnsembleTaskSignals(prompt);
+  const highUncertainty = shape.uncertainty === 'high';
+  const fableTopology = typeof plan.strategy === 'string' && plan.strategy.startsWith('fable-');
+  const comparable = signals.comparableOutput || signals.explicitDisagreement;
+
+  const reasonCodes = [];
+  if (highUncertainty) reasonCodes.push('high-uncertainty');
+  if (signals.highStakes) reasonCodes.push('high-stakes');
+  if (signals.comparableOutput) reasonCodes.push('comparable-output');
+  if (signals.explicitDisagreement) reasonCodes.push('explicit-disagreement');
+
+  let selected = (highUncertainty || signals.highStakes) && comparable && fableTopology;
+  if (signals.creativeGeneration) {
+    selected = false;
+    reasonCodes.push('ensemble-excluded-creative-generation');
+  }
+  if (signals.mechanicalWork) {
+    selected = false;
+    reasonCodes.push('ensemble-excluded-mechanical-work');
+  }
+  if (prohibitions.includes('ensemble')) {
+    selected = false;
+    reasonCodes.push('user-prohibited-ensemble');
+  }
+  if (shape.hostCapabilities && shape.hostCapabilities.subagents === 'unavailable') {
+    selected = false;
+    reasonCodes.push('ensemble-subagents-unavailable');
+  }
+  if (plan.fallback && plan.fallback.disposition === 'blocked') {
+    selected = false;
+    reasonCodes.push('ensemble-base-plan-blocked');
+  }
+
+  plan.reasonCodes = unique([...(plan.reasonCodes || []), ...reasonCodes]);
+  if (!selected) {
+    plan.ensemble = null;
+    return contract;
+  }
+
+  const selectionReason = signals.explicitDisagreement
+    ? 'ensemble-disagreement-deliverable'
+    : signals.highStakes
+      ? 'ensemble-high-stakes-comparable-output'
+      : 'ensemble-high-uncertainty-comparable-output';
+
+  plan.ensemble = {
+    maxCandidates: ENSEMBLE_MAX_CANDIDATES,
+    diversity: ['model', 'prompt', 'evidence'],
+    synthesis: 'preserve-disagreement',
+    verifier: 'independent',
+    reasonCodes: unique([selectionReason, ...reasonCodes]),
+  };
+  plan.patterns = unique([...(plan.patterns || []), 'parallel-self-consistency']);
+  plan.requiredInvariants = unique([
+    ...(plan.requiredInvariants || []),
+    'preserve-disagreement',
+    'independent-ensemble-verifier',
+  ]);
+  plan.reasonCodes = unique([...(plan.reasonCodes || []), 'ensemble-review-selected']);
+  return contract;
+}
+
+module.exports = {
+  ENSEMBLE_MAX_CANDIDATES,
+  applyEnsemblePolicy,
+  detectEnsembleTaskSignals,
+};

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

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const {
+  createDegradedRouterContract,
+  validateRouterContract,
+} = require('./router-contract');
+const { applyEnsemblePolicy } = require('./ensemble-policy');
+
+/**
+ * Harness Kernel Router
+ *
+ * tier-router remains the human-readable classifier/guide detector. The
+ * kernel consumes its versioned side-channel JSON contract instead of
+ * scraping human-readable stdout. Phase 2 selects an execution topology, but
+ * the router still only emits a plan: executors retain responsibility for
+ * spawning agents, creating workspaces, running tools, and enforcing gates.
+ * Phase 4 attaches ensemble-review only as a post-selection modifier.
+ */
+
+const INVARIANT_TEXT = {
+  'scope-lock': 'Route before execution: stay inside the authorized task/repository scope.',
+  'verify-before-claim': 'Verify before claim: completion claims require objective evidence appropriate to the change.',
+  'replan-after-repeated-failure': 'Re-plan on repetition: after 3 same-signature failures, stop micro-retrying and zoom out/re-diagnose.',
+  'loop-budget': 'Stop iterative-single when its explicit iteration budget is exhausted.',
+  'objective-verification': 'Use an objective check for iterative work; self-critique alone is not verification.',
+  'stage-contracts': 'Fable stages must have explicit stage contracts and pass conditions.',
+  'cold-verification': 'Fable delivery requires a cold/independent verifier where specified.',
+  'parallel-scope-contract': 'Parallel work requires declared independent scopes and non-overlapping/read-only writes.',
+  'synthesis-barrier': 'Do not claim parallel completion until all workstreams reach the synthesis barrier.',
+  'handoff-contracts': 'Multi-agent workspace work uses orchestrator-owned handoff contracts; workers do not form a peer mesh.',
+  'workspace-state': 'Durable workspace state remains scoped to the workspace and existing state conventions.',
+  'pre-action-approval': 'Irreversible/external side effects require approval before the exact payload executes.',
+  'preserve-disagreement': 'Ensemble synthesis must retain unresolved minority positions and evidence gaps.',
+  'independent-ensemble-verifier': 'Ensemble delivery requires a verifier independent from the candidate identities; agreement alone is not proof.',
+};
+
+const SKILL_TEXT = {
+  'tdd': 'tdd: useful for behavioral changes where executable tests can drive the implementation.',
+  'verification-loop': 'verification-loop: useful for systematic build/lint/test/diff evidence before delivery.',
+  'fable-mode': 'fable-mode / fable-discipline: useful for macro planning or deliberate multi-agent decomposition.',
+  'fable-discipline': null,
+  'multi-agent-workspace': 'multi-agent-workspace: useful when durable bounded delegation, handoffs, or workspace memory are required.',
+};
+
+function sanitizeClassifierOutput(stdout) {
+  const lines = String(stdout || '').split(/\r?\n/);
+  const filtered = [];
+  let skipLegacyContinuation = false;
+
+  for (const line of lines) {
+    if (line.includes('=> BASE EXECUTION LOOP:')) {
+      skipLegacyContinuation = true;
+      continue;
+    }
+    if (skipLegacyContinuation && line.includes('Track exactly ONE item in-progress')) {
+      skipLegacyContinuation = false;
+      continue;
+    }
+    skipLegacyContinuation = false;
+    filtered.push(line);
+  }
+
+  return filtered.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd();
+}
+
+function readStructuredContract(contractPath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(contractPath, 'utf8'));
+    const validation = validateRouterContract(parsed);
+    if (!validation.valid) {
+      return createDegradedRouterContract(
+        'router-contract-invalid',
+        `Structured router contract failed validation: ${validation.errors.join('; ')}`,
+      );
+    }
+    return parsed;
+  } catch (err) {
+    return createDegradedRouterContract(
+      'router-contract-unavailable',
+      `Structured router contract unavailable: ${err.message}`,
+    );
+  }
+}
+
+function resolvePrompt(prompt, stdinPayload) {
+  if (prompt) return prompt;
+  if (!stdinPayload) return '';
+  try {
+    const payload = JSON.parse(stdinPayload);
+    return typeof payload.prompt === 'string' ? payload.prompt : '';
+  } catch (_) {
+    return '';
+  }
+}
+
+function printWorkflowPlan(plan) {
+  const visible = {
+    schemaVersion: plan.schemaVersion,
+    routingStatus: plan.routingStatus,
+    tier: plan.tier,
+    strategy: plan.strategy,
+    strategySelection: plan.strategySelection,
+    actionGate: plan.actionGate,
+    limits: plan.limits,
+    parallelism: plan.parallelism,
+    workspace: plan.workspace,
+    memory: plan.memory,
+    verification: plan.verification,
+    ensemble: plan.ensemble,
+    fallback: plan.fallback,
+    reasonCodes: plan.reasonCodes,
+  };
+  console.log(`\n=> ROUTER WORKFLOW PLAN (JSON): ${JSON.stringify(visible)}`);
+}
+
+function printKernelContract(plan) {
+  console.log('\n=> REQUIRED HARNESS INVARIANTS:');
+  for (const invariant of plan.requiredInvariants || []) {
+    console.log(`   - ${invariant}: ${INVARIANT_TEXT[invariant] || 'Required by the selected workflow plan.'}`);
+  }
+
+  console.log('\n=> SUGGESTED SKILLS (ADVISORY — no fixed workflow order):');
+  if (Array.isArray(plan.suggestedSkills) && plan.suggestedSkills.length > 0) {
+    const emitted = new Set();
+    for (const skill of plan.suggestedSkills) {
+      if (emitted.has(skill)) continue;
+      const text = Object.prototype.hasOwnProperty.call(SKILL_TEXT, skill) ? SKILL_TEXT[skill] : `${skill}: advisory for the selected topology.`;
+      if (text) console.log(`   - ${text}`);
+      emitted.add(skill);
+      if (skill === 'fable-mode') emitted.add('fable-discipline');
+    }
+    if (plan.strategy && plan.strategy.startsWith('fable-')) {
+      console.log('   - Use these selectively; Tier 3/Fable does not create a universal skill pipeline.');
+    }
+  } else if (plan.strategy === 'direct-single') {
+    console.log('   - No mandatory domain skill. Prefer the bounded direct path and load a focused skill only when it adds value.');
+  } else if (plan.strategySelection === 'deferred') {
+    console.log('   - Strategy is deferred/unclassified. Do not infer triviality; choose the smallest justified approach from task evidence.');
+  } else {
+    console.log('   - No additional skill suggestion from the workflow plan.');
+  }
+
+  if (plan.ensemble) {
+    console.log(`\n=> ENSEMBLE REVIEW: bounded to ${plan.ensemble.maxCandidates} candidates; synthesis=${plan.ensemble.synthesis}; verifier=${plan.ensemble.verifier}. Preserve minority positions and do not claim improvement without paired evidence.`);
+  }
+
+  if (plan.actionGate && plan.actionGate.required) {
+    console.log(`\n=> ACTION GATE REQUIRED: ${plan.actionGate.reasonCodes.join(', ')}; disposition=${plan.actionGate.disposition}. The router only declares this requirement; execution must not bypass approval.`);
+  }
+
+  if (plan.fallback && plan.fallback.disposition !== 'none') {
+    console.log(`\n=> ROUTING FALLBACK: ${plan.fallback.disposition}/${plan.fallback.mode}; ${plan.fallback.reasonCodes.join(', ')}.`);
+  }
+
+  if (plan.routingStatus === 'degraded') {
+    console.log('\n=> ROUTING DEGRADATION: Structured routing is degraded. Keep the strategy deferred unless independent evidence supports a route; do not silently downgrade to Tier 1/direct execution.');
+  }
+
+  console.log('\n=> ORCHESTRATION POLICY: Do not enforce workflow order. Enforce workflow invariants from the plan; suggested skills remain advisory. The router plans; execution components execute.');
+}
+
+function run(prompt, stdinPayload) {
+  const classifierPath = path.join(__dirname, 'tier-router.js');
+  const contractPath = path.join(os.tmpdir(), `harness-router-${process.pid}-${crypto.randomUUID()}.json`);
+  const args = prompt ? [classifierPath, prompt] : [classifierPath];
+  const result = spawnSync(process.execPath, args, {
+    input: prompt ? undefined : stdinPayload,
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      HARNESS_ROUTER_CONTRACT_PATH: contractPath,
+    },
+  });
+
+  if (result.error) {
+    console.error(`[Harness Kernel] Failed to execute tier-router.js: ${result.error.message}`);
+    process.exit(1);
+  }
+
+  const sanitized = sanitizeClassifierOutput(result.stdout);
+  if (sanitized) console.log(sanitized);
+  if (result.stderr) process.stderr.write(result.stderr);
+
+  const contract = readStructuredContract(contractPath);
+  applyEnsemblePolicy(contract, resolvePrompt(prompt, stdinPayload));
+  try {
+    fs.rmSync(contractPath, { force: true });
+  } catch (err) {
+    // Temporary contract cleanup is best effort only.
+  }
+
+  printWorkflowPlan(contract.workflowPlan);
+  printKernelContract(contract.workflowPlan);
+
+  if (result.status !== 0) process.exit(result.status === null ? 1 : result.status);
+}
+
+const prompt = process.argv.slice(2).join(' ');
+if (prompt) {
+  run(prompt, null);
+} else if (process.stdin.isTTY) {
+  run('', null);
+} else {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { input += chunk; });
+  process.stdin.on('end', () => run('', input));
+}