harness-everything 0.15.0 → 0.16.1

package/ci/workflow-execution-contract.test.js

@@ -1,133 +1,55 @@
 #!/usr/bin/env node
 'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
+const fs = require('fs'), os = require('os'), path = require('path'), { spawnSync } = require('child_process');
 const ROOT = path.resolve(__dirname, '..');
-const { recordBudgetEvent, resetWorkflowBudget } = require(path.join(ROOT, 'hooks/scripts/lib/workflow-runtime.js'));
-let failed = 0;
-
-function check(condition, message) {
-  if (condition) console.log(`  PASS ${message}`);
-  else { console.error(`  FAIL ${message}`); failed++; }
-}
-
-function runNode(args, options = {}) {
-  return spawnSync(process.execPath, args, { cwd: ROOT, encoding: 'utf8', ...options });
-}
-
-console.log('=== Workflow Execution Enforcement ===');
-
-for (const rel of [
-  'harness-everything/scripts/kernel-router.js',
-  'harness-everything/scripts/kernel-router-core.js',
-  'hooks/scripts/workflow-gate.js',
-  'hooks/scripts/workflow-stop-gate.js',
-  'hooks/scripts/workflow-disposition.js',
-]) {
-  const result = runNode(['--check', path.join(ROOT, rel)]);
-  check(result.status === 0, `${rel} parses as valid JavaScript`);
-}
-
-const routed = runNode([
-  path.join(ROOT, 'harness-everything/scripts/kernel-router.js'),
-  'audit the entire repository architecture and coordinate multiple modules',
-]);
-check(routed.status === 0, 'enforced kernel route exits successfully');
-check(routed.stdout.includes('"strategy":"fable-staged"'), 'macro prompt selects fable-staged');
-check(routed.stdout.includes('WORKFLOW EXECUTION CONTRACT (MANDATORY WHEN SELECTED)'), 'wrapper emits mandatory execution contract');
-check(routed.stdout.includes('Execute the selected workflow to resolution'), 'wrapper requires workflow resolution');
-check(routed.stdout.includes('workflow-uncovered-scope'), 'wrapper exposes only explicit evidence-backed escape path');
-check(!routed.stdout.includes('execution remains advisory after evaluation'), 'wrapper removes advisory-execution runtime wording');
-
-const disposition = fs.readFileSync(path.join(ROOT, 'hooks/scripts/workflow-disposition.js'), 'utf8');
-check(disposition.includes("'workflow-uncovered-scope'"), 'escape supports workflow-uncovered-scope');
-check(disposition.includes("'host-capability-unavailable'"), 'escape supports host-capability-unavailable');
-check(disposition.includes('generic simple/routine/already-clear reasons are intentionally rejected'), 'generic confidence-based escape reasons are rejected');
-check(disposition.includes('--scope is required') && disposition.includes('--evidence is required') && disposition.includes('--stage-id must name'), 'escape requires a declared stage, scope and evidence');
-
-const hooks = JSON.parse(fs.readFileSync(path.join(ROOT, 'hooks/hooks.json'), 'utf8'));
-check((hooks.hooks.PreToolUse || []).some(entry => entry.id === 'harness:pre:workflow-gate'), 'Claude hook wiring includes pre-mutation workflow gate');
-check((hooks.hooks.Stop || []).some(entry => entry.id === 'harness:stop:workflow-completion-gate'), 'Claude hook wiring includes workflow completion gate');
-
-
-const budgetRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-budget-'));
-function budgetContext(name, strategy = 'iterative-single', limits = {}) {
-  const file = path.join(budgetRoot, name, 'workflow-run.json');
-  return {
-    root: path.join(budgetRoot, name),
-    sessionId: name,
-    sessionDir: path.join(budgetRoot, name),
-    file,
-    workflow: {
-      schemaVersion: 2,
-      sessionId: name,
-      workflowId: `wf-${name}`,
-      state: 'running',
-      strategy,
-      revision: 0,
-      workflowPlan: {
-        strategy,
-        limits: { maxIterations: 8, maxRevisionRounds: 2, maxReplans: 2, maxWorkers: 4, ...limits },
-      },
-    },
-  };
-}
-function expectBudgetBlock(fn, reason, message) {
-  try {
-    fn();
-    check(false, message);
-  } catch (error) {
-    check(error.code === 'HARNESS_WORKFLOW_BUDGET' && error.message.includes(reason), `${message} (${error.message})`);
+const runtime = require(path.join(ROOT, 'hooks/scripts/lib/workflow-runtime.js'));
+let failed=0;
+function check(c,m){if(c)console.log('  PASS '+m);else{console.error('  FAIL '+m);failed++;}}
+function runNode(args){return spawnSync(process.execPath,args,{cwd:ROOT,encoding:'utf8'});}
+console.log('=== Workflow Guidance Contract ===');
+for(const rel of ['harness-everything/scripts/kernel-router.js','hooks/scripts/workflow-gate.js','hooks/scripts/workflow-stop-gate.js','hooks/scripts/workflow-disposition.js','hooks/scripts/state-persist.js','hooks/scripts/rule-of-3.js','hooks/scripts/rule-of-3-tracker.js'])check(runNode(['--check',path.join(ROOT,rel)]).status===0,rel+' parses as valid JavaScript');
+const ctx={workflow:{workflowPlan:{limits:{maxIterations:8,maxRevisionRounds:2,maxReplans:2,maxWorkers:4}}}};
+for(const type of ['iteration','revision','replan','worker-acquire'])check(runtime.recordBudgetEvent(ctx,type,{evidence:'fixture'}).advisory===true,type+' is advisory rather than blocking');
+check(runtime.mutationProbeReservations(ctx)===0,'mutation probes reserve no capacity');
+check(runtime.registerMutationProbe(ctx,'x','y')===null,'mutation probe registration is a no-op');
+check(runtime.resetWorkflowBudget(ctx,'legacy').retired===true,'reset-budget API is retired compatibility only');
+check(!runtime.WORKFLOW_CONTROLLER_COMMANDS.has('reset-budget'),'reset-budget is no longer a controller command');
+const rs=fs.readFileSync(path.join(ROOT,'hooks/scripts/lib/workflow-runtime.js'),'utf8');
+check(!rs.includes('.mutation-probes.lock'),'runtime contains no mutation-probe lock');
+check(!rs.includes('budget-exhausted'),'runtime contains no budget-exhausted transition');
+const gs=fs.readFileSync(path.join(ROOT,'hooks/scripts/workflow-gate.js'),'utf8');
+check(!gs.includes('registerMutationProbe')&&!gs.includes('recordBudgetEvent'),'workflow gate has no probe/budget enforcement');
+check(gs.includes('[Workflow Reminder]'),'workflow gate emits reminders');
+const r3=fs.readFileSync(path.join(ROOT,'hooks/scripts/rule-of-3.js'),'utf8');
+check(r3.includes('state.count >= 3'),'Rule of 3 uses fixed third-failure boundary');
+check(!r3.includes('blockForHumanDecision'),'Rule of 3 has no second-stage permanent hard lock');
+const tr=fs.readFileSync(path.join(ROOT,'hooks/scripts/rule-of-3-tracker.js'),'utf8');
+check(!tr.includes('threshold = 2')&&!tr.includes('threshold = 4'),'Rule of 3 has no category-specific thresholds');
+const oc=fs.readFileSync(path.join(ROOT,'opencode-plugin/index.mjs'),'utf8');
+check(!oc.includes('action: "hard_lock"'),'OpenCode has no permanent hard-lock action');
+const hk=JSON.parse(fs.readFileSync(path.join(ROOT,'hooks/hooks.json'),'utf8'));
+check(!hk.hooks.PermissionDenied,'obsolete mutation-probe PermissionDenied hook is removed');
+
+const freshnessRoot=fs.mkdtempSync(path.join(os.tmpdir(),'harness-fable-freshness-'));
+try{
+  const contracts=path.join(freshnessRoot,'contracts'),evidence=path.join(freshnessRoot,'evidence');fs.mkdirSync(contracts);fs.mkdirSync(evidence);
+  const run={runId:'freshness-run',planId:'freshness-plan',sessionId:'freshness-session',stageIds:['worker','verifier']};
+  const workerAt=Date.now()-10000,verifierAt=Date.now()-5000;
+  const stages=[
+    {stageId:'worker',agent:'fable-worker',workerId:'worker-1',writeSet:['src/x.js'],dependsOn:[],checkCommand:'worker-check',verifiedAt:new Date(workerAt).toISOString()},
+    {stageId:'verifier',agent:'fable-verifier',workerId:'verifier-1',writeSet:[],dependsOn:['worker'],checkCommand:'verify-check',verifiedAt:new Date(verifierAt).toISOString()},
+  ];
+  for(const stage of stages){
+    const contract={...stage,runId:run.runId,planId:run.planId,sessionId:run.sessionId,status:'pass'};
+    fs.writeFileSync(path.join(contracts,stage.stageId+'.json'),JSON.stringify(contract));
+    fs.writeFileSync(path.join(evidence,stage.stageId+'.json'),JSON.stringify({status:'pass',exitCode:0,planId:run.planId,runId:run.runId,stageId:stage.stageId,sessionId:run.sessionId,checkCommand:stage.checkCommand,observedAt:stage.verifiedAt,workerId:stage.workerId}));
   }
-}
-
-const iterationCtx = budgetContext('iteration');
-for (let i = 0; i < 8; i++) recordBudgetEvent(iterationCtx, 'iteration', { evidence: `mutation-${i + 1}` });
-check(iterationCtx.workflow.budget.counters.iterations === 8, 'iteration budget allows exactly maxIterations events');
-expectBudgetBlock(() => recordBudgetEvent(iterationCtx, 'iteration', { evidence: 'mutation-9' }), 'iteration-budget-exhausted', 'ninth iterative event is blocked');
-check(iterationCtx.workflow.state === 'blocked' && iterationCtx.workflow.budget.state === 'budget-exhausted', 'iteration exhaustion is persisted as blocked evidence');
-const persistedIteration = JSON.parse(fs.readFileSync(iterationCtx.file, 'utf8'));
-check(persistedIteration.blockReason === 'iteration-budget-exhausted', 'budget exhaustion survives on-disk workflow state');
-
-const isolatedCtx = budgetContext('isolated');
-recordBudgetEvent(isolatedCtx, 'iteration', { evidence: 'independent-run' });
-check(isolatedCtx.workflow.budget.counters.iterations === 1, 'another run/session has independent accounting');
-check(iterationCtx.workflow.budget.counters.iterations === 8, 'independent accounting does not reset exhausted run');
-
-resetWorkflowBudget(iterationCtx, 'new explicitly authorized attempt');
-check(iterationCtx.workflow.state === 'pending' && iterationCtx.workflow.budget.epoch === 1, 'budget reset is explicit, auditable, and starts a new epoch');
-check(iterationCtx.workflow.budget.counters.iterations === 0 && iterationCtx.workflow.budget.resets.length === 1, 'reset clears only the target run counters and retains history');
-
-const revisionCtx = budgetContext('revision', 'fable-staged');
-recordBudgetEvent(revisionCtx, 'revision', { evidence: 'verifier-fail-1' });
-recordBudgetEvent(revisionCtx, 'revision', { evidence: 'verifier-fail-2' });
-expectBudgetBlock(() => recordBudgetEvent(revisionCtx, 'revision', { evidence: 'verifier-fail-3' }), 'revision-budget-exhausted', 'third revision round is blocked');
-
-const replanCtx = budgetContext('replan', 'fable-staged');
-recordBudgetEvent(replanCtx, 'replan', { evidence: 'replan-1' });
-recordBudgetEvent(replanCtx, 'replan', { evidence: 'replan-2' });
-expectBudgetBlock(() => recordBudgetEvent(replanCtx, 'replan', { evidence: 'replan-3' }), 'replan-budget-exhausted', 'third full replan is blocked');
-
-const workerCtx = budgetContext('workers', 'fable-parallel');
-for (const id of ['w1', 'w2', 'w3', 'w4']) recordBudgetEvent(workerCtx, 'worker-acquire', { workerId: id });
-check(Object.keys(workerCtx.workflow.budget.activeWorkers).length === 4, 'worker accounting reaches but does not exceed maxWorkers');
-recordBudgetEvent(workerCtx, 'worker-release', { workerId: 'w1' });
-recordBudgetEvent(workerCtx, 'worker-acquire', { workerId: 'w5' });
-check(Object.keys(workerCtx.workflow.budget.activeWorkers).length === 4 && workerCtx.workflow.budget.activeWorkers.w5, 'released worker capacity is reusable');
-
-const overflowCtx = budgetContext('worker-overflow', 'fable-parallel');
-for (const id of ['w1', 'w2', 'w3', 'w4']) recordBudgetEvent(overflowCtx, 'worker-acquire', { workerId: id });
-expectBudgetBlock(() => recordBudgetEvent(overflowCtx, 'worker-acquire', { workerId: 'w5' }), 'worker-budget-exhausted', 'fifth concurrent worker is blocked');
-
-try { fs.rmSync(budgetRoot, { recursive: true, force: true }); } catch (_) {}
-
-const pluginHooks = JSON.parse(fs.readFileSync(path.join(ROOT, 'plugins/harness-everything/hooks/hooks.json'), 'utf8'));
-check((pluginHooks.hooks.PreToolUse || []).some(entry => (entry.hooks || []).some(hook => /workflow-gate\.js/.test(hook.command || ''))), 'OpenAI plugin hook package carries workflow gate adapter');
-check((pluginHooks.hooks.Stop || []).some(entry => (entry.hooks || []).some(hook => /workflow-stop-gate\.js/.test(hook.command || ''))), 'OpenAI plugin hook package carries workflow completion adapter');
-
-console.log(`\n${failed === 0 ? 'PASS' : 'FAIL'}: workflow execution enforcement (${failed} failure${failed === 1 ? '' : 's'})`);
-process.exit(failed === 0 ? 0 : 1);
+  const workflow={lastMutationAt:0,verification:{independent:true}};
+  const fresh=runtime.unresolvedStages({runRoot:freshnessRoot,run},workflow,workerAt);
+  check(!fresh.includes('independent-verifier-missing'),'Fable independent verifier accepts edits older than verifier evidence');
+  const stale=runtime.unresolvedStages({runRoot:freshnessRoot,run},workflow,verifierAt+1000);
+  check(stale.includes('independent-verifier-missing'),'Fable independent verifier is invalidated by newer handoff shell-edit evidence');
+}finally{fs.rmSync(freshnessRoot,{recursive:true,force:true});}
+
+console.log('\n'+(failed===0?'PASS':'FAIL')+': workflow guidance contract ('+failed+' failures)');
+process.exit(failed===0?0:1);

package/ci/workflow-plan-consumers-edge.test.js

@@ -63,7 +63,7 @@ const result = spawnSync(process.execPath, [hook], {
   encoding: 'utf8',
   env: { ...process.env, HARNESS_STATE_HOME: stateHome },
 });
-check(result.status === 2, 'a check from another session cannot resolve this run contract');
+check(result.status === 0 && /session|correlat|resolve/i.test(result.stderr), 'a cross-session check is reported without resolving the run contract');
 const manifest = JSON.parse(fs.readFileSync(path.join(isolated.runRoot, 'contracts', 'verify.json'), 'utf8'));
 check(manifest.status === 'planned', 'cross-session check leaves the target contract unmodified');
 

package/ci/workflow-plan-consumers.test.js

@@ -92,7 +92,7 @@ const runA = prepareRun({
   sessionId: 'phase3-session',
 });
 check(JSON.stringify(runA.execution.batches) === JSON.stringify([['architecture', 'security'], ['synthesis']]), 'parallel plan emits dependency-safe ready batches');
-check(runA.execution.limits.maxWorkers === 4, 'run manifest retains the numeric worker cap');
+check(runA.execution.limits.maxWorkers === 4, 'run manifest retains maxWorkers as an advisory planning hint');
 check(fs.existsSync(path.join(runA.runRoot, 'contracts', 'security.json')), 'run-scoped stage contract is written');
 check(fs.existsSync(path.join(runA.runRoot, 'contracts', 'synthesis.json')), 'downstream stage has its own contract');
 
@@ -119,9 +119,9 @@ const wideRun = prepareRun({
   runId: 'phase3-wide-parallel',
   sessionId: 'wide-session',
 });
-check(wideRun.execution.batches.length === 2, 'ready set larger than worker cap is deterministically chunked');
-check(wideRun.execution.batches.every(batch => batch.length <= 4), 'no dispatchable batch exceeds maxWorkers=4');
-check(wideRun.execution.batches.flat().length === 6, 'worker-cap chunking preserves every ready stage');
+check(wideRun.execution.batches.length === 1, 'ready set is not hard-chunked by the advisory maxWorkers hint');
+check(wideRun.execution.batches[0].length === 6, 'all dependency-ready stages remain dispatchable');
+check(wideRun.execution.batches.flat().length === 6, 'advisory worker guidance preserves every ready stage');
 
 const stagedRun = prepareRun({
   routerContract: stagedContract,
@@ -235,7 +235,7 @@ const ambiguousResult = spawnSync(process.execPath, [contractHook], {
   encoding: 'utf8',
   env: { ...process.env, HARNESS_STATE_HOME: stateHome },
 });
-check(ambiguousResult.status === 2, 'ambiguous same-command correlation blocks acceptance');
+check(ambiguousResult.status === 0 && /ambiguous|multiple/i.test(ambiguousResult.stderr), 'ambiguous same-command correlation is reported without blocking');
 for (const runId of ['ambiguous-a', 'ambiguous-b']) {
   const manifest = JSON.parse(fs.readFileSync(path.join(getWorkspaceStateRoot(workspace), 'fable-runs', runId, 'contracts', 'same-check.json'), 'utf8'));
   check(manifest.status === 'planned', `${runId} remains unmodified after ambiguous check`);
@@ -280,7 +280,7 @@ check(inScope.status === 0 && /in-scope/.test(inScope.stdout), 'declared in-scop
 check(runScope('PreToolUse').status === 0, 'next burst starts from rolled-forward baseline');
 fs.writeFileSync(path.join(gitWorkspace, 'docs', 'oops.txt'), 'unexpected\n');
 const outOfScope = runScope('PostToolUse');
-check(outOfScope.status === 2 && /OUT-OF-SCOPE/.test(outOfScope.stderr), 'undeclared worker edit is rejected by scope guard');
+check(outOfScope.status === 0 && /OUT-OF-SCOPE/.test(outOfScope.stderr), 'undeclared worker edit is reported without blocking');
 
 const contractDoc = fs.readFileSync(path.join(ROOT, 'fable-mode', 'CONTRACT-FORMAT.md'), 'utf8');
 const orchestratorDoc = fs.readFileSync(path.join(ROOT, 'fable-mode', 'agents', 'fable-orchestrator.md'), 'utf8');

package/docs/architecture.md

@@ -4,22 +4,22 @@ This document describes Harness runtime architecture and integration boundaries.
 
 ## Architectural Overview
 
-Harness is a **behavior and workflow supervisor**, not one universal fixed workflow. The router chooses the smallest sufficient execution topology; once selected, that topology becomes a lifecycle contract. The model retains freedom over reasoning, tools, and implementation technique inside the contract.
+Harness is a **behavior and workflow observer/router**, not a universal fixed workflow or scheduler. The router chooses a useful topology; the model remains free to adapt execution.
 
 The minimal kernel establishes:
 
 - scope/tier before mutation,
-- a selected workflow topology when task evidence supports one,
+- a selected workflow topology as planning guidance when task evidence supports one,
 - applicability evaluation for every suggested skill before omission,
 - objective evidence before completion,
 - bounded re-plan/recovery after repeated failure,
-- explicit blocked/degraded/escape state instead of silent workflow deletion.
+- explicit warnings/degraded/escape evidence instead of silent workflow deletion.
 
-> **Mandatory applicable workflow; flexible reasoning/implementation inside it.**
+> **Guidance-first workflow; flexible reasoning/implementation and execution.**
 >
-> A suggested skill can be `not-applicable` after evaluating its real flow. A selected topology cannot be replaced with a direct path merely because the model is confident. Escape is only for genuinely uncovered workflow scope and requires evidence.
+> Suggested skills and topology are evaluated from their real flows. Missing or skipped cognitive workflow steps produce evidence/reminders rather than persistent Harness locks.
 
-This avoids both extremes: the old universal Tier-2/Tier-3 pipeline and a purely advisory system where the model can rationalize away verification, staging, documentation, or other applicable obligations.
+This avoids both extremes: no universal Tier-2/Tier-3 pipeline and no maze of self-deadlocking cognitive gates.
 
 ```mermaid
 flowchart TD
@@ -50,7 +50,7 @@ flowchart TD
 - required invariants,
 - suggested skills that require applicability evaluation,
 - the visible routing checkpoint,
-- a workflow execution contract.
+- a workflow guidance.
 
 The router does not tell the model *how* to solve each stage. It decides what lifecycle shape is required. `direct-single`, `iterative-single`, `fable-staged`, `fable-parallel`, and `fable-multi-agent-workspace` remain deliberately small, non-overlapping topology choices.
 
@@ -58,7 +58,7 @@ The router does not tell the model *how* to solve each stage. It decides what li
 
 Router suggestions remain useful domain/workflow knowledge, not a universal sequence. Before omission, the agent reads the complete `SKILL.md` entry and evaluates `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules. Name/description/router-summary or “routine task” is insufficient evidence.
 
-The selected topology is stronger. Once selected, it must be entered and resolved unless the runtime records a permitted workflow escape with uncovered scope + evidence. Covered obligations survive the escape.
+The selected topology is a structured planning aid; it does not become a persistent execution lock.
 
 ### Runtime workflow state
 
@@ -66,16 +66,16 @@ On host paths that can persist it, `kernel-router.js` records session-scoped `wo
 
 For selected Fable topologies on Claude:
 
-- `workflow-gate.js` checks supported shell/direct mutation, actual direct/patch targets, and registered Git worktree isolation before major-workflow mutation; Fable also requires a run bound to the workflow/session identity;
+- `workflow-gate.js` observes supported mutation/worktree/Fable state and emits reminders;
 - Fable owns stage contracts, `dependsOn`/`writeSet`, validated execution batches, objective per-stage checks, synthesis, cold verification, and bounded re-plans;
-- `workflow-stop-gate.js` rejects completion while correlated stage contracts remain unresolved;
-- `workflow-disposition.js` starts/replans within budget, records blockers, and permits only declared-stage evidence-backed escape (`workflow-uncovered-scope` or `host-capability-unavailable`). Covered obligations, isolation, and independent verification survive escape. See [runtime transitions and limitations](workflow-runtime.md).
+- `workflow-stop-gate.js` reports unresolved stage/verification evidence without rejecting Stop;
+- `workflow-disposition.js` records explicit lifecycle/audit decisions; numeric budgets are no longer authoritative control state.
 
 Other topologies use their own applicable mechanisms: loop budgets, regular verification stop-gates, action gates, and task-specific skills. Mechanism coverage is not assumed identical across hosts.
 
 ### Scoped runtime advisories and capabilities
 
-Two kernel mechanisms adjust plans without changing the mandatory-workflow contract:
+Two kernel mechanisms annotate plans without creating hard workflow enforcement:
 
 - **Ensemble policy (`harness-everything/scripts/ensemble-policy.js`):** an advisory plan annotation, not a separate topology. It is selected only when uncertainty is high (or stakes are high) **and** the task asks for comparable outputs or preserves explicit disagreement **and** the selected strategy is already `fable-*`. Creative generation, mechanical bulk work, an explicit user prohibition, unavailable subagents, or a blocked base plan force exclusion. When selected, the plan caps at 3 candidates with `preserve-disagreement` synthesis, an independent verifier, and `parallel-self-consistency` pattern invariants. Covered by deterministic mechanism tests; no live-host effectiveness claim follows from the annotation alone.
 - **Single-use memory capability (`kernel-router.js#issueMemoryCapability`):** when the selected plan permits memory writes, the router issues one capability token bound to `sessionId`/`workflowId` with a stored SHA-256 hash (`memoryAuthorization`, coordinator-only writer role, `usedAt` tracking). Plans with `memory.write === 'none'` receive no capability. This binds a memory write to the workflow that authorized it; it is not a general credential and proves nothing about a live host honoring the binding.
@@ -84,11 +84,11 @@ Two kernel mechanisms adjust plans without changing the mandatory-workflow contr
 
 On the Claude hook path, three narrowly scoped `PreToolUse` guards sit alongside the workflow/action gates:
 
-- `boundary-guard.js` (Grep/Glob/Read): hard-blocks whole-file reads over 512KB without `offset`/`limit` and searches inside known noise directories (`node_modules`, `.git`, build output, etc.). Fails open on parse/lookup errors.
+- `boundary-guard.js` (Grep/Glob/Read): warns about very large reads and noisy search roots; it fails open.
 - `depth-guard.js` (Write): blocks overwriting an existing file that was never Read earlier in the session transcript. New files are unaffected. Fails open on parse/lookup errors.
 - `context-compact.js`: estimates working-tree context pressure from `git status`/`git diff --numstat` so later stages can compact or halt before lost-in-the-middle degradation.
 
-Shell mutation accounting is per-tool-call: `workflow-isolation.js` fingerprints observed effects per tool-use identity, `state-persist.js` settles probes in a single ordered handler, and `workflow-mutation-denied.js` discards probes for denied shell executions so a denial never counts as an observed mutation. See [runtime transitions and limitations](workflow-runtime.md). These are mechanism-tested behaviors on the packaged hook surface, not proof that a live session loaded or fired them.
+Shell mutation observation is best-effort evidence for reminders. The old mutation-probe reservation/lock subsystem was retired by #190.
 
 ## Integration Touchpoints
 
@@ -98,23 +98,23 @@ Harness aligns to each host's actual lifecycle/tool APIs. Shared skill text defi
 
 Runtime state includes hook metadata, workflow lifecycle, circuit-breaker counters, handoff/verification evidence, and WAL-style session state. Skill content is independently discoverable and remains useful on instruction-only surfaces.
 
-### Claude Code — hook-enforced mechanisms
+### Claude Code — hook guidance plus explicit safety boundaries
 
 The installer configures native lifecycle hooks and project skills.
 
 - `SessionStart`: bootstrap/restoration.
-- `UserPromptSubmit`: kernel routing + active workflow contract.
-- `PreToolUse`: workflow bypass gate, action gate, rule-of-3, boundary/depth/context guards, subagent scope guard.
+- `UserPromptSubmit`: kernel routing + workflow guidance.
+- `PreToolUse`: workflow/boundary/depth/scope reminders, plus separate action permission and Rule-of-3 boundaries.
 - `PostToolUse`: outcomes, state, repeated-failure evidence, stage checks.
-- `Stop`: action-gate audit, selected-Fable completion gate, and ordinary verify-before-claim stop gate.
+- `Stop`: action-gate audit plus non-blocking workflow/verification reminders.
 
-These hooks make some lifecycle obligations mechanically enforceable. They still do not prove a real session loaded/fired them; live evidence remains separate.
+These hooks make reminders observable; they do not promote cognitive workflow guidance into hard enforcement.
 
 ### OpenCode — plugin enforcement, scoped live verification
 
 The retained [OpenCode evidence](../benchmarks/results/live-host/opencode-2026-09-16/README.md) supports **project-scope `.js` loading and edit/verification state on OpenCode 1.18.31 (macOS)**. The final snapshot is **post-reset**. Hard-lock is an **interactive observation** with **no retained blocked-tool trace**; reflection was **operator-seeded** and then agent-rewritten. Global scope, npm-package installation, and other OpenCode versions remain unverified.
 
-This evidence does not establish the new mandatory-workflow lifecycle on OpenCode. That requires its own adapter/evidence before parity is claimed.
+This evidence predates #190 and does not establish behavioral effectiveness of the current guidance-first lifecycle.
 
 ### Cursor — skills plus advisory rules
 
@@ -161,7 +161,7 @@ flowchart TD
     R -- No --> Block
 ```
 
-The orchestrator controls lifecycle and completion; workers do not create peer-to-peer meshes or widen their own write scope. The model remains creative inside each bounded stage, while stage existence/checks/termination are contract state.
+The orchestrator coordinates lifecycle and evidence; scope drift is reported for review rather than turned into a cognitive deadlock.
 
 ## Cognitive OS and Skill Mesh
 

package/docs/enforcement-locks.md

@@ -1,114 +1,53 @@
-# Enforcement and Lock Diagnostic Flows
-
-Harness has several mechanisms that can deny a tool call or delay completion. Only one of them is a repeated-failure circuit breaker. Use the emitted mechanism name and the flows below before describing a denial as a lock problem.
-
-This guide describes the repository's current hook wiring. Mechanical enforcement depends on the host and installation surface; see [Platform Capability Matrix](platform-capabilities.md) before generalizing a behavior to every host.
-
-## Lifecycle map
-
-On the Claude hook surface, a request enters the router before tool use. Pre-tool gates decide whether a tool call may start, post-tool hooks record outcomes, and stop gates decide whether the turn may finish.
-
-```mermaid
-flowchart TD
-    A["User prompt"] --> B["Kernel router<br/>select workflow contract"]
-    B --> C["Pre-tool gates"]
-    C --> D{"Tool allowed?"}
-    D -- "No" --> E["Emit gate-specific reason<br/>and recovery"]
-    D -- "Yes" --> F["Execute tool"]
-    F --> G["Post-tool outcome tracking"]
-    G --> H{"Turn stopping?"}
-    H -- "No" --> C
-    H -- "Yes" --> I["Completion gates"]
-    I --> J{"Obligations resolved?"}
-    J -- "Yes" --> K["Evidence-backed completion"]
-    J -- "No" --> E
+# Guidance and Safety Boundary Diagnostic Flows
+
+Harness deliberately separates **cognitive guidance** from **authorization/safety boundaries**.
+
+## Classification
+
+| Mechanism | Behavior | Hard block? |
+|---|---|---|
+| Workflow routing/state | Remind about selected topology, stale/blocked descriptive state, missing Fable correlation, or safer worktree usage | No |
+| Iteration/revision/replan/worker guidance | Planning hints only | No |
+| Verification / Stop | Remind when no successful verification is observed after an edit | No |
+| Boundary guard | Warn about very large reads or noisy search roots | No |
+| Depth guard | Remind when editing a file that has not been inspected | No |
+| Subagent scope guard | Report ambiguous/out-of-scope changes for review | No |
+| Atomic commit check | Warn when changes look broader than one atomic concern | No |
+| Fable contract test | Record pass/fail/ambiguity/dependency evidence and warn | No |
+| Rule of 3 | Third matching failure requires a zoom-out reflection before more mutation | **Yes — intentional cognitive boundary** |
+| Action/permission gate | User/host authorization for destructive or external side effects | **Yes — trust boundary** |
+
+## Rule of 3
+
+```text
+same signature #1 -> record
+same signature #2 -> record
+same signature #3 -> pause mutation and require zoom-out
+reflection accepted -> count resets
+later #1/#2/#3 -> another zoom-out
 ```
 
-The important separation is:
-
-- **Pre-tool denial:** the requested operation did not run.
-- **Post-tool tracking:** the operation ran and its outcome updated state.
-- **Stop denial:** the turn cannot claim completion yet; it does not necessarily prevent the next tool call.
-- **Approval request:** the exact destructive or external action waits for authorization; it is not a retry lock.
-
-## Which mechanism stopped progress?
-
-Start with the prefix in the error or hook message. Do not infer the mechanism only from the fact that a command did not run.
-
-```mermaid
-flowchart TD
-    A["Operation or completion blocked"] --> B{"Message prefix or condition"}
-    B -- "RULE OF 3" --> C["Repeated-failure circuit breaker"]
-    B -- "Workflow gate" --> D["Workflow entry, state,<br/>run, or worktree precondition"]
-    B -- "Action gate or permission" --> E["Exact side effect needs approval"]
-    B -- "Workflow Completion Gate" --> F["Selected workflow obligations unresolved"]
-    B -- "Stop Gate" --> G["Edits lack later successful verification"]
-    B -- "Boundary, depth, context,<br/>or scope guard" --> H["Guard-specific policy denial"]
-    C --> I["Follow Rule of 3 recovery flow"]
-    D --> J["Satisfy named workflow precondition"]
-    E --> K["Approve, reject, or change exact payload"]
-    F --> L["Resolve stages or report blocked state"]
-    G --> M["Run a relevant check or state why not applicable"]
-    H --> N["Follow the emitted guard reason"]
-```
-
-If a message has no Harness prefix, check the host permission system and the tool's own error before changing Harness state.
-
-## Mechanism reference
-
-| Mechanism | Trigger | What it blocks | State and persistence | Recovery |
-|---|---|---|---|---|
-| Rule of 3 | The same normalized shell failure signature reaches its category threshold. Defaults to 3; timeout and permission use 2; environment and dependency use 4. | Mutating tools. Read-only investigation remains available, and the required zoom-out report is the only permitted write. | Session-scoped `rule-of-3-state.json`. A second trip of the same signature after one accepted reflection becomes a human-decision hard lock. | First trip: produce a fresh valid `zoom-out-report.md`. Repeat trip: human runs `npm run harness:reset`, starts a new session, or uses `/clear`. |
-| Workflow gate | Active workflow state or entry contract is incompatible with the requested mutation; examples include blocked/failed/satisfied state, missing correlated Fable run, or missing linked worktree for major work. | The requested mutation. Read-only commands and trusted workflow-controller commands have narrow exceptions. | Session workflow state. Major-workflow isolation is a hard precondition, not an automatic fallback. | Use the exact message: enter a linked worktree, start/replan through the controller, resolve blocked state, or submit a new task after satisfaction. |
-| Action gate | A shell rule or structured destructive/external action matches the policy. | Only the exact action payload; its hash is used for audit correlation. | Approval/audit state records pending, executed, failed, or rejected disposition. | Approve or reject through the host flow, or change the action. Approval of one payload does not authorize a different payload. |
-| Workflow completion gate | A selected workflow is stopping with unresolved stage, correlation, or verification obligations. | Completion. On a repeated stop-hook attempt it records a blocked state instead of looping forever. | `workflow-run.json` plus correlated stage/handoff state. | Resolve the named obligation. If genuinely blocked, report the blocker rather than claim completion. |
-| Ordinary stop gate | A dirty tree contains edits with no later successful verification-like command. | Completion once per edit batch. It is intentionally a bounce, not a persistent cage. | `stop-gate-state.json` remembers the edit timestamp already bounced. | Run a targeted test/build/lint check, or explicitly state why verification is not applicable and stop again. |
-| Boundary/depth/context/scope guards | A guard-specific read, write, context-pressure, or subagent-scope condition matches. | The matching tool or workflow step. | Mechanism-specific; these are not Rule of 3 counters. | Follow the emitted reason and the corresponding architecture documentation. |
-
-## Rule of 3 state transitions
-
-The tracker hashes a normalized failure together with category, file path, and command context. A different signature starts a new counter. A confirmed successful action clears recovery state.
-
-```mermaid
-stateDiagram-v2
-    [*] --> Counting
-    Counting --> Counting: same signature below threshold
-    Counting --> Reflecting: threshold reached
-    Reflecting --> Counting: valid fresh report with RESUME
-    Reflecting --> Escalating: valid fresh report with ESCALATE
-    Counting --> HardLocked: same signature trips after reflection
-    HardLocked --> [*]: human reset or new session
-    Counting --> [*]: confirmed success
-    Escalating --> HardLocked: mutation retried and signature trips again
-```
-
-A valid reflection report must be newer than the failure that tripped the breaker, contain `Goal`, `Failed Attempts`, `Verified Facts`, `Diagnosis`, and `Decision`, and end in a `RESUME` or `ESCALATE` decision. A stale report cannot release a later trip.
-
-## Pre-tool ordering and overlapping denials
+There are no category-specific 2/4 thresholds and no second-stage permanent hard lock.
 
-The configured Claude pre-tool order is workflow gate, action gate, Rule of 3, then the narrower boundary/depth/context/scope guards for their matched tools. This means the first emitted denial identifies the condition reached on that call; it does not prove that every later gate would pass.
+## Workflow reminders
 
-For example:
+A workflow may be marked `blocked`, `failed`, or carry legacy `budget-exhausted` evidence. Those states are useful diagnostics but no longer cause `workflow-gate.js` to reject mutation.
 
-1. A force push may first fail the workflow gate if the selected workflow has not been entered.
-2. After workflow entry is fixed, the action gate may still require approval for the same force push.
-3. Rule of 3 is relevant only when repeated tracked failures reached the signature threshold; it should not be reset to bypass workflow or approval requirements.
+Missing verification at Stop similarly produces a reminder rather than a bounce.
 
-Treat each denial independently and re-evaluate after satisfying its stated condition.
+## Why #190 removed hard workflow enforcement
 
-## Host and evidence boundary
+The previous numeric enforcement required mutation probes, stale-probe recovery, shared counters, exact-limit exceptions, shell classification, reset controllers, and a filesystem lock. #190 removed that chain instead of hardening it.
 
-The hook sequence above is the canonical Claude package wiring. The local OpenAI/Codex plugin packages related lifecycle adapters, while general installer paths and the public Skills-only artifact may be advisory rather than mechanically enforced. OpenCode has a separate plugin implementation and a narrower retained live-host evidence boundary.
+The design test is simple:
 
-Repository mechanism tests show that packaged code follows its tested contract. They do not by themselves prove that a particular live host loaded the package, fired the hook, or improved agent behavior. Record live-host evidence before making that stronger claim.
+> If better cognitive guidance requires another lock, lease, heartbeat, counter-recovery protocol, or parser exception, prefer a reminder.
 
-## Source map
+## Troubleshooting
 
-Use these implementation files when this guide and runtime appear to disagree:
+When a Harness message appears:
 
-- `hooks/hooks.json` — lifecycle wiring and order.
-- `hooks/scripts/rule-of-3.js` and `rule-of-3-tracker.js` — counter, thresholds, reflection, and hard-lock behavior.
-- `hooks/scripts/workflow-gate.js` and `workflow-stop-gate.js` — mutation and completion workflow contracts.
-- `hooks/scripts/action-gate.js` and `action-gate-rules.json` — approval policy and audit behavior.
-- `hooks/scripts/stop-gate.js` — ordinary one-bounce verification behavior.
-- [Harness Architecture](architecture.md) and [Workflow Runtime](workflow-runtime.md) — broader runtime contracts and limitations.
+1. If it is a **Reminder**, use the evidence to improve the next action, but there is no Harness reset needed.
+2. If it is the **Rule of 3** third-failure boundary, complete the requested zoom-out report.
+3. If it is an **action/permission** decision, follow the host/user approval flow.
+4. Do not edit Harness state files merely to recover from a numeric workflow limit; those limits are no longer enforced.

package/docs/mechanism-first-skill-mesh.md

@@ -4,7 +4,7 @@ Harness coordinates independently useful skills through a small workflow runtime
 
 The preferred shape is:
 
-> **mandatory applicable workflow + local skill autonomy + narrow runtime mechanisms**
+> **guidance-first workflow + local skill autonomy + narrow runtime mechanisms**
 
 Platform-specific enforcement claims remain bounded by [platform-capabilities.md](platform-capabilities.md).
 
@@ -19,7 +19,7 @@ A skill should answer:
 3. **What workflow/mechanism do I expose?** A local flow, verifier, script, gate, or stable result when useful.
 4. **What evidence means I am done?** A check, artifact, or explicit blocked state.
 
-The router may surface several skills. Those suggestions must be evaluated from their actual `SKILL.md` flows before omission. They are **not** automatically all executed. Separately, the router selects one smallest sufficient outer topology. **The selected topology is mandatory for the run.**
+The router may surface several skills. Those suggestions must be evaluated from their actual `SKILL.md` flows before omission. They are **not** automatically all executed. Separately, the router selects one smallest sufficient outer topology. **The selected topology guides the run.**
 
 ## Why Not One Global Skill Sequence?
 

package/docs/philosophy.md

@@ -9,14 +9,14 @@ The mechanism/enforcement boundary remains platform-specific; see [Platform Capa
 ## Core Philosophy: Constrain Lifecycle, Not Reasoning
 
 1. **Reasoning autonomy remains high.** The model chooses implementation technique, tools, decomposition details, and tactics inside the selected workflow.
-2. **Applicable workflow is mandatory.** Once routing selects a topology, it must be executed to resolution. Model confidence, “simple”, “routine”, and “already clear” are not escape conditions.
+2. **Applicable workflow is guidance: routing should make useful structure visible without taking execution agency away from the model/user.
 3. **Skill applicability is explicit.** Router-suggested skills are read/evaluated before omission. A suggestion can be `not-applicable` when its actual flow does not match; a selected topology is stronger and cannot simply be skipped.
 4. **Escape is conditional, not default.** If the selected workflow genuinely cannot represent part of the task, record the uncovered scope and evidence, then allow model-defined handling only for that uncovered portion.
 5. **Mechanisms beat stronger wording.** Important lifecycle transitions should use structured state, objective evidence, hooks/plugins, exit codes, and completion gates where the host supports them rather than escalating `MUST`/`CRITICAL` prose.
 
 This principle can be summarized as:
 
-> **Mandatory applicable workflow; flexible reasoning/implementation inside it; evidence-backed escape only where the workflow does not cover the task.**
+> **guidance-first applicable workflow; flexible reasoning/implementation inside it; evidence-backed escape only where the workflow does not cover the task.**
 
 The goal is not to make the model less capable. It is to prevent capability/confidence from silently deleting engineering obligations such as verification, bounded re-planning, stage checks, documentation checks, or safety gates when those obligations are applicable.