harness-everything 0.3.6 → 0.4.0

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-phase3-edge-'));
+const workspace = path.join(tempRoot, 'workspace');
+const stateHome = path.join(tempRoot, 'state-home');
+fs.mkdirSync(path.join(workspace, '.git'), { recursive: true });
+process.env.HARNESS_STATE_HOME = stateHome;
+
+const { buildRouterContract } = require(path.join(ROOT, 'harness-everything', 'scripts', 'router-contract.js'));
+const { prepareRun } = require(path.join(ROOT, 'fable-mode', 'scripts', 'workflow-plan-consumer.js'));
+const { pathWithinScope } = require(path.join(ROOT, 'hooks', 'scripts', 'lib', 'fable-contracts.js'));
+
+let failed = 0;
+function check(condition, message) {
+  if (condition) console.log(`  PASS ${message}`);
+  else { console.error(`  FAIL ${message}`); failed++; }
+}
+
+const staged = buildRouterContract({
+  routingStatus: 'ok',
+  recommendedTier: 'Tier 3 (Macro Task)',
+  rationale: 'phase3 edge fixture',
+  reasonCodes: ['phase3-edge'],
+  signals: { macroScope: true, dependentStages: true },
+});
+
+const overlapping = prepareRun({
+  routerContract: staged,
+  workspaceRoot: workspace,
+  runId: 'staged-overlap',
+  stages: [
+    { stageId: 'a', goal: 'a', agent: 'worker', task: 'a', dependsOn: [], writeSet: ['src/shared'], inputs: [], expectedOutputs: [] },
+    { stageId: 'b', goal: 'b', agent: 'worker', task: 'b', dependsOn: [], writeSet: ['src/shared/file.js'], inputs: [], expectedOutputs: [] },
+  ],
+});
+check(JSON.stringify(overlapping.execution.batches) === JSON.stringify([['a'], ['b']]), 'fable-staged serializes overlapping writers instead of rejecting them');
+check(pathWithinScope('src/auth/token.js', 'src/auth'), 'scope matcher accepts already-normalized paths');
+
+const isolated = prepareRun({
+  routerContract: staged,
+  workspaceRoot: workspace,
+  runId: 'session-b-only',
+  sessionId: 'session-b',
+  stages: [{
+    stageId: 'verify', goal: 'verify', agent: 'fable-verifier', task: 'verify', dependsOn: [], writeSet: [],
+    inputs: [], expectedOutputs: [], checkCommand: 'node --test isolated.test.js', passCondition: 'exit 0',
+  }],
+});
+const hook = path.join(ROOT, 'hooks', 'scripts', 'contract-test.js');
+const result = spawnSync(process.execPath, [hook], {
+  cwd: workspace,
+  input: JSON.stringify({
+    hook_event_name: 'PostToolUse', tool_name: 'Bash', session_id: 'session-a', cwd: workspace,
+    tool_input: { command: 'node --test isolated.test.js' }, tool_response: { exitCode: 0, stdout: 'PASS' },
+  }),
+  encoding: 'utf8',
+  env: { ...process.env, HARNESS_STATE_HOME: stateHome },
+});
+check(result.status === 2, 'a check from another session cannot resolve this 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');
+
+try { fs.rmSync(tempRoot, { recursive: true, force: true }); } catch (_) {}
+console.log(`\n${failed === 0 ? 'PASS' : 'FAIL'}: #85 Phase 3 edge contracts (${failed} failure${failed === 1 ? '' : 's'})`);
+process.exit(failed === 0 ? 0 : 1);

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

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-phase3-'));
+const stateHome = path.join(tempRoot, 'state-home');
+const workspace = path.join(tempRoot, 'workspace');
+fs.mkdirSync(workspace, { recursive: true });
+fs.mkdirSync(path.join(workspace, '.git'), { recursive: true });
+process.env.HARNESS_STATE_HOME = stateHome;
+
+const { buildRouterContract } = require(path.join(ROOT, 'harness-everything', 'scripts', 'router-contract.js'));
+const {
+  derivePlanId,
+  getWorkspaceStateRoot,
+  prepareRun,
+  validateStageGraph,
+} = require(path.join(ROOT, 'fable-mode', 'scripts', 'workflow-plan-consumer.js'));
+const { consumeWorkspacePlan } = require(path.join(ROOT, 'multi-agent-workspace', 'scripts', 'consume-workflow-plan.js'));
+const { pathWithinScope } = require(path.join(ROOT, 'hooks', 'scripts', 'lib', 'fable-contracts.js'));
+
+let failed = 0;
+function check(condition, message) {
+  if (condition) console.log(`  PASS ${message}`);
+  else {
+    console.error(`  FAIL ${message}`);
+    failed++;
+  }
+}
+
+function expectThrow(fn, pattern, message) {
+  try {
+    fn();
+    check(false, message);
+  } catch (err) {
+    check(pattern.test(err.message), `${message} (${err.message})`);
+  }
+}
+
+function contractFor(signals) {
+  return buildRouterContract({
+    routingStatus: 'ok',
+    recommendedTier: 'Tier 3 (Macro Task)',
+    rationale: 'phase 3 test fixture',
+    reasonCodes: ['phase3-test'],
+    signals: { macroScope: true, ...signals },
+  });
+}
+
+const parallelContract = contractFor({ independentWorkstreams: true, readOnly: true });
+const stagedContract = contractFor({ dependentStages: true });
+const workspaceContract = contractFor({ multiSession: true, reusableSpecialists: true, crossDomain: true });
+
+console.log('=== #85 Phase 3 Workflow Plan Consumers ===');
+check(parallelContract.workflowPlan.strategy === 'fable-parallel', 'fixture selects fable-parallel');
+check(stagedContract.workflowPlan.strategy === 'fable-staged', 'fixture selects fable-staged');
+check(workspaceContract.workflowPlan.strategy === 'fable-multi-agent-workspace', 'fixture selects fable-multi-agent-workspace');
+
+const planIdA = derivePlanId(parallelContract);
+const planIdB = derivePlanId(JSON.parse(JSON.stringify(parallelContract)));
+check(planIdA === planIdB && /^plan-[0-9a-f]{16}$/.test(planIdA), 'planId is deterministic and content-addressed');
+
+const parallelStages = [
+  {
+    stageId: 'security', goal: 'read security state', agent: 'fable-worker-sonnet', task: 'audit security',
+    inputs: [], expectedOutputs: ['security notes'], outputPath: null, dependsOn: [], writeSet: [],
+    checkCommand: 'node --test security.test.js', passCondition: 'exit 0',
+  },
+  {
+    stageId: 'architecture', goal: 'read architecture state', agent: 'fable-worker-sonnet', task: 'audit architecture',
+    inputs: [], expectedOutputs: ['architecture notes'], outputPath: null, dependsOn: [], writeSet: [],
+    checkCommand: 'node --test architecture.test.js', passCondition: 'exit 0',
+  },
+  {
+    stageId: 'synthesis', goal: 'synthesize results', agent: 'fable-worker-sonnet', task: 'write synthesis',
+    inputs: [], expectedOutputs: ['summary'], outputPath: 'reports/summary.md', dependsOn: ['security', 'architecture'],
+    writeSet: ['reports/summary.md'], checkCommand: 'node --test synthesis.test.js', passCondition: 'exit 0',
+  },
+];
+
+const runA = prepareRun({
+  routerContract: parallelContract,
+  stages: parallelStages,
+  workspaceRoot: workspace,
+  runId: 'phase3-run-a',
+  sessionId: 'phase3-session',
+});
+check(JSON.stringify(runA.execution.batches) === JSON.stringify([['architecture', 'security'], ['synthesis']]), 'parallel plan emits dependency-safe ready batches');
+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');
+
+const runB = prepareRun({
+  routerContract: parallelContract,
+  stages: parallelStages,
+  workspaceRoot: workspace,
+  runId: 'phase3-run-b',
+  sessionId: 'other-session',
+});
+check(runA.planId === runB.planId, 'same router plan shares deterministic planId across executions');
+check(runA.runRoot !== runB.runRoot, 'same stageIds in concurrent runs never share mutable contract paths');
+
+const stagedRun = prepareRun({
+  routerContract: stagedContract,
+  stages: [
+    { stageId: 'one', goal: 'one', agent: 'fable-worker-sonnet', task: 'one', dependsOn: [], writeSet: ['src/one'], inputs: [], expectedOutputs: [] },
+    { stageId: 'two', goal: 'two', agent: 'fable-worker-sonnet', task: 'two', dependsOn: [], writeSet: ['src/two'], inputs: [], expectedOutputs: [] },
+  ],
+  workspaceRoot: workspace,
+  runId: 'phase3-staged',
+});
+check(JSON.stringify(stagedRun.execution.batches) === JSON.stringify([['one'], ['two']]), 'fable-staged serializes otherwise independent stages');
+
+expectThrow(() => validateStageGraph([
+  { stageId: 'broken', goal: 'x', agent: 'a', task: 'x', dependsOn: ['missing'], writeSet: [], inputs: [], expectedOutputs: [] },
+]), /unresolved dependency/, 'unknown dependency is rejected');
+
+expectThrow(() => validateStageGraph([
+  { stageId: 'a', goal: 'a', agent: 'a', task: 'a', dependsOn: ['b'], writeSet: [], inputs: [], expectedOutputs: [] },
+  { stageId: 'b', goal: 'b', agent: 'a', task: 'b', dependsOn: ['a'], writeSet: [], inputs: [], expectedOutputs: [] },
+]), /cyclic/, 'dependency cycle is rejected');
+
+expectThrow(() => prepareRun({
+  routerContract: parallelContract,
+  workspaceRoot: workspace,
+  runId: 'phase3-overlap',
+  stages: [
+    { stageId: 'a', goal: 'a', agent: 'a', task: 'a', dependsOn: [], writeSet: ['src/auth'], inputs: [], expectedOutputs: [] },
+    { stageId: 'b', goal: 'b', agent: 'a', task: 'b', dependsOn: [], writeSet: ['src/auth/token.js'], inputs: [], expectedOutputs: [] },
+  ],
+}), /write-set overlap/, 'parallel write-set overlap rejects dispatch');
+
+check(pathWithinScope(' M src/auth/token.js', 'src/auth'), 'scope matcher accepts descendants of a declared path');
+check(!pathWithinScope(' M src/author.js', 'src/auth'), 'scope matcher uses path boundaries, not string prefixes');
+
+// Workspace consumer: preserve existing role/memory ownership and add only correlation.
+const aiDir = path.join(workspace, '.ai');
+fs.mkdirSync(aiDir, { recursive: true });
+const originalHandoff = {
+  schemaVersion: 1,
+  state: 'ready',
+  workspaceKey: 'fixture',
+  repoRoot: workspace,
+  selectedAgents: [{ id: 'security-reviewer', provider: 'agency-agents', source: 'catalog/security.md' }],
+  memoryIndex: '.ai/memory/index.json',
+  generatedAt: 'fixture',
+};
+fs.writeFileSync(path.join(aiDir, 'handoff.json'), JSON.stringify(originalHandoff, null, 2));
+const correlatedHandoff = consumeWorkspacePlan({
+  routerContract: workspaceContract,
+  workspaceRoot: workspace,
+  runId: 'phase3-workspace',
+});
+check(JSON.stringify(correlatedHandoff.selectedAgents) === JSON.stringify(originalHandoff.selectedAgents), 'workspace consumer preserves selected roles/provenance');
+check(correlatedHandoff.memoryIndex === originalHandoff.memoryIndex, 'workspace consumer preserves existing memory index');
+check(correlatedHandoff.workflowCorrelation.planId === derivePlanId(workspaceContract), 'workspace handoff is correlated to router planId');
+check(correlatedHandoff.workflowCorrelation.runId === 'phase3-workspace', 'workspace handoff records shared runId');
+check(correlatedHandoff.workflowCorrelation.rolePolicy === 'existing-workspace-selection', 'router does not take ownership of role selection');
+
+// Exact stage-check correlation and evidence.
+const checkRun = prepareRun({
+  routerContract: stagedContract,
+  workspaceRoot: workspace,
+  runId: 'phase3-check',
+  sessionId: 'check-session',
+  stages: [{
+    stageId: 'verify', goal: 'verify', agent: 'fable-verifier', task: 'verify output', dependsOn: [], writeSet: [],
+    inputs: [], expectedOutputs: ['evidence'], checkCommand: 'node --test phase3.test.js', passCondition: 'exit 0',
+  }],
+});
+const contractHook = path.join(ROOT, 'hooks', 'scripts', 'contract-test.js');
+const checkPayload = {
+  hook_event_name: 'PostToolUse',
+  tool_name: 'Bash',
+  session_id: 'check-session',
+  cwd: workspace,
+  tool_input: { command: 'node --test phase3.test.js' },
+  tool_response: { exitCode: 0, stdout: 'PASS phase3' },
+};
+const checkResult = spawnSync(process.execPath, [contractHook], {
+  cwd: workspace,
+  input: JSON.stringify(checkPayload),
+  encoding: 'utf8',
+  env: { ...process.env, HARNESS_STATE_HOME: stateHome },
+});
+check(checkResult.status === 0, `exact correlated stage check passes (${checkResult.stderr.trim() || 'no stderr'})`);
+const resolvedContract = JSON.parse(fs.readFileSync(path.join(checkRun.runRoot, 'contracts', 'verify.json'), 'utf8'));
+check(resolvedContract.status === 'pass', 'contract-test resolves exactly one run-scoped stage contract');
+check(resolvedContract.verificationEvidence === 'evidence/verify.json', 'stage contract links run-scoped verification evidence');
+const evidence = JSON.parse(fs.readFileSync(path.join(checkRun.runRoot, 'evidence', 'verify.json'), 'utf8'));
+check(evidence.planId === checkRun.planId && evidence.runId === checkRun.runId && evidence.stageId === 'verify', 'verification evidence correlates plan/run/stage');
+
+// Same command in two active contracts must not mutate either without enough correlation.
+for (const runId of ['ambiguous-a', 'ambiguous-b']) {
+  prepareRun({
+    routerContract: stagedContract,
+    workspaceRoot: workspace,
+    runId,
+    sessionId: 'ambiguous-session',
+    stages: [{
+      stageId: 'same-check', goal: 'verify', agent: 'fable-verifier', task: 'verify', dependsOn: [], writeSet: [],
+      inputs: [], expectedOutputs: [], checkCommand: 'npm test', passCondition: 'exit 0',
+    }],
+  });
+}
+const ambiguousResult = spawnSync(process.execPath, [contractHook], {
+  cwd: workspace,
+  input: JSON.stringify({
+    hook_event_name: 'PostToolUse', tool_name: 'Bash', session_id: 'ambiguous-session', cwd: workspace,
+    tool_input: { command: 'npm test' }, tool_response: { exitCode: 0, stdout: 'ok' },
+  }),
+  encoding: 'utf8',
+  env: { ...process.env, HARNESS_STATE_HOME: stateHome },
+});
+check(ambiguousResult.status === 2, 'ambiguous same-command correlation blocks acceptance');
+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`);
+}
+
+// Full subagent-scope hook: declared path passes; undeclared path fails.
+const gitWorkspace = path.join(tempRoot, 'git-workspace');
+fs.mkdirSync(path.join(gitWorkspace, 'src', 'auth'), { recursive: true });
+fs.mkdirSync(path.join(gitWorkspace, 'docs'), { recursive: true });
+fs.writeFileSync(path.join(gitWorkspace, 'src', 'auth', 'token.txt'), 'base\n');
+fs.writeFileSync(path.join(gitWorkspace, 'docs', 'base.txt'), 'base\n');
+for (const args of [
+  ['init'],
+  ['config', 'user.email', 'phase3@example.invalid'],
+  ['config', 'user.name', 'Phase3 Test'],
+  ['add', '.'],
+  ['commit', '-m', 'baseline'],
+]) {
+  const result = spawnSync('git', args, { cwd: gitWorkspace, encoding: 'utf8' });
+  assert.strictEqual(result.status, 0, result.stderr);
+}
+prepareRun({
+  routerContract: stagedContract,
+  workspaceRoot: gitWorkspace,
+  runId: 'scope-run',
+  sessionId: 'scope-session',
+  stages: [{ stageId: 'edit-auth', goal: 'edit auth', agent: 'worker', task: 'edit auth', dependsOn: [], writeSet: ['src/auth'], inputs: [], expectedOutputs: [] }],
+});
+const scopeHook = path.join(ROOT, 'hooks', 'scripts', 'subagent-scope-guard.js');
+function runScope(event) {
+  return spawnSync(process.execPath, [scopeHook], {
+    cwd: gitWorkspace,
+    input: JSON.stringify({ hook_event_name: event, tool_name: 'Task', session_id: 'scope-session', cwd: gitWorkspace }),
+    encoding: 'utf8',
+    env: { ...process.env, HARNESS_STATE_HOME: stateHome },
+  });
+}
+check(runScope('PreToolUse').status === 0, 'scope guard captures machine-readable write-set snapshot');
+fs.writeFileSync(path.join(gitWorkspace, 'src', 'auth', 'token.txt'), 'changed\n');
+const inScope = runScope('PostToolUse');
+check(inScope.status === 0 && /in-scope/.test(inScope.stdout), 'declared in-scope worker edit is attributed and accepted');
+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');
+
+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');
+const workspaceDoc = fs.readFileSync(path.join(ROOT, 'multi-agent-workspace', 'references', 'orchestration.md'), 'utf8');
+check(contractDoc.includes('dependsOn') && contractDoc.includes('writeSet'), 'Fable contract documentation requires dependency/write-set declarations');
+check(orchestratorDoc.includes('workflow-plan-consumer.js') && orchestratorDoc.includes('planId'), 'Fable orchestrator consumes structured plan and correlation ids');
+check(workspaceDoc.includes('does not decide whether a task deserves multiple agents'), 'workspace no longer independently chooses topology from task size');
+
+try { fs.rmSync(tempRoot, { recursive: true, force: true }); } catch (_) {}
+console.log(`\n${failed === 0 ? 'PASS' : 'FAIL'}: #85 Phase 3 workflow-plan consumers (${failed} failure${failed === 1 ? '' : 's'})`);
+process.exit(failed === 0 ? 0 : 1);

package/docs/architecture.md

@@ -1,99 +1,179 @@
 # Harness Architecture
 
-This document details the internal architecture, lifecycle, and integration touchpoints of the Harness behavior layer.
+This document describes the internal architecture, lifecycle, and integration boundaries of the Harness behavior layer. The current cross-platform claim boundary is centralized in [platform-capabilities.md](platform-capabilities.md); host sections here must remain consistent with it.
 
 ---
 
 ## Architectural Overview
 
-Harness acts as a **system supervisor** wrapping around your AI development sessions. Instead of controlling the model's generation directly, it leverages native hook systems (like Claude Code's lifecycle hooks) and instruction files (like `.cursorrules` or `.github/copilot-instructions.md`) to inject contextual guardrails.
+Harness is a **system supervisor**, not a universal workflow engine. Skills remain independently useful, while runtime mechanisms establish a small cross-cutting contract around software work.
 
-At the skill layer, Harness is designed as a [mechanism-first skill mesh](mechanism-first-skill-mesh.md): each skill remains independently useful, while routers, gates, hooks, scripts, exit codes, and compact return values provide coordination at decision points.
+The architecture follows a mechanism-first skill mesh with a **minimal kernel**:
 
-The diagram below outlines the full lifecycle of a task under Harness:
+- classify scope before mutation,
+- require evidence before completion claims,
+- stop repeated same-signature micro-retries and re-plan,
+- leave domain skill selection, ordering, planning style, and delegation to the agent.
+
+> **Do not enforce workflow order. Enforce workflow invariants.**
+
+This is intentionally different from the older design where Tier 2 implied a fixed TDD/checklist pipeline and Tier 3 implied a mandatory Fable/multi-agent pipeline.
 
 ```mermaid
 flowchart TD
     subgraph User_Session [User Session]
-        U([User Request]) --> Boot[bootstrap.js: Session Start]
+        U([User Request]) --> Boot[bootstrap.js: Session Start / restore]
+    end
+
+    subgraph Kernel [Harness Kernel]
+        Boot --> Preflight[Environment / integration discovery]
+        Preflight --> KR[kernel-router.js]
+        KR --> TR[tier-router.js<br/>classifier + guide discovery]
+        TR --> Inv[Inject minimal invariants]
+        Inv --> Choice[Agent chooses useful skills / tactics]
     end
 
-    subgraph OS_Kernel [Harness Engine]
-        Boot -->|Check Handoff Checkpoint| Preflight[preflight.js: Environment Audit]
-        Preflight --> Router{tier-router.js: Task Triage}
-        
-        Router -->|Tier 1: Trivial Task| T1[Direct Execution - No Plans]
-        Router -->|Tier 2: Standard Task| T2[tdd: Test-Driven Development]
-        Router -->|Tier 3: Macro Task| T3[fable-mode: Multi-Agent Spawn]
-        T2 & T3 --> TDW[todo-driven-workflow: Base Execution Checklist]
+    subgraph Execution [Agent-Controlled Execution]
+        Choice --> Tools[Tool calls / edits / tests]
+        Tools --> Evidence{Evidence supports completion?}
+        Evidence -- Yes --> Done[Evidence-backed completion]
+        Evidence -- No --> Retry[Diagnose / iterate]
     end
 
-    subgraph Defense_Safety [Circuit Breakers]
-        T1 & TDW --> Tools[Agent Tool Call]
-        Tools -->|PreToolUse| CG[context-compact.js: Bloat Warning]
-        Tools -->|PreToolUse| CB{rule-of-3.js: Circuit Breaker}
-        
-        CB -->|Fails 3x| ZO(zoom-out: Halt, Reflect & Fact-Check)
-        ZO -->|Fresh diagnosis: RESUME| Tools
-        CB -->|Succeeds| Done[Success / Finish]
+    subgraph Defense [Runtime Boundaries]
+        Retry --> CB{Same-signature failure x3?}
+        CB -- No --> Tools
+        CB -- Yes --> ZO[zoom-out / fresh diagnosis]
+        ZO --> Tools
     end
 
-    subgraph Continuous_Learning [Continuous Learning]
-        ZO -->|Genuine human decision / 2nd trip| Human[Human Decision & Guidance]
-        Human --> SE[self-evolve: Deep Reflection]
-        Done -->|Complex Breakthrough| SE
-        SE --> RunSR[self-regression.js: CI Check]
-        RunSR -->|Pass 100%| Mem[(Long-term Memory / RULES.md)]
-        Mem -.->|Immunize| Preflight
+    subgraph Learning [Optional Learning / State]
+        Done --> Record[Record / self-evolve when useful]
     end
 
-    style OS_Kernel fill:#eceff1,stroke:#37474f,stroke-width:2px,color:#000000
-    style Defense_Safety fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#000000
-    style Continuous_Learning fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px,color:#000000
+    style Kernel fill:#eceff1,stroke:#37474f,stroke-width:2px,color:#000000
+    style Defense fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#000000
+    style Learning fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px,color:#000000
 ```
 
+### Router responsibilities
+
+`kernel-router.js` is the public runtime entry point. It delegates heuristic classification and dynamic guide/skill discovery to `tier-router.js`, then converts the result into the Harness contract:
+
+- recommended Tier + rationale,
+- required invariants,
+- advisory skill suggestions.
+
+The kernel deliberately suppresses the old fixed `BASE EXECUTION LOOP` wording so that a host selecting `tdd`, `security-review`, `repo-docs`, or another peer skill cannot accidentally replace or bypass the cross-cutting Harness contract.
+
+`harness-everything` remains the public/manual skill entry point for routing, debugging, and re-routing. `install-cognitive-os` remains the explanatory/manual entry point for the Discover → Think → Try → Summarize → Record policy. Automatic correctness must not depend on either one winning host peer-skill selection first.
+
 ---
 
-## Integration touchpoints
+## Integration Touchpoints
+
+Harness aligns to each host's real capabilities. Enforcement strength is platform-specific; shared skill text does not prove mechanism parity.
+
+### Self-healing and placement
+
+`harness-everything/scripts/self-heal.js` audits supported integration touchpoints and can re-run the idempotent installer to repair missing pieces. If a user intentionally removed an integration, respect that choice.
+
+A platform's native files stay where that platform expects them. Harness-owned runtime state converges under the platform's `harness-everything/` state directory, while skills remain in each platform's native skill location. `manifest.json` records installed artifacts so uninstall can remove only Harness-owned files.
+
+### Runtime state vs. skill content
+
+Runtime state includes hook metadata, circuit-breaker counters, handoff/verification timestamps, and WAL-style session state. Skill content is separate and independently discoverable. This separation lets a domain skill remain useful even when a host does not support Harness runtime hooks.
+
+---
+
+## Host Adapters
+
+### 1. Claude Code — hook-enforced
+
+The installer configures native lifecycle hooks and project skills.
+
+- `SessionStart`: `bootstrap.js` restores prior state and audits integrations.
+- `UserPromptSubmit`: `kernel-router.js` establishes routing + invariants before peer/domain skill execution.
+- `PreToolUse`: circuit breaker, boundary/depth/context guards, and subagent scope guards can block supported tool calls.
+- `PostToolUse`: records outcomes/state and tracks repeated failures.
+- `Stop`: `stop-gate.js` prevents an edit batch from being claimed complete without successful verification evidence.
 
-Harness is designed to align with the unique capabilities of various AI IDEs and CLI tools — but those capabilities are not equivalent across platforms, and this repo does not pretend otherwise.
+The prompt hook is intentionally lightweight: it does **not** prescribe TODO/TDD/Fable order. It gives the model the rails and lets the model orchestrate itself.
 
-**Self-healing:** integration touchpoints can drift — installed from one editor, opened in another. `harness-everything/scripts/self-heal.js` audits all six touchpoints below and re-runs the idempotent installer to backfill whatever is missing. On Claude Code, `bootstrap.js` performs the audit at SessionStart and reports missing touchpoints (repair is left to the model so an intentionally removed file isn't silently re-created every session); on hook-less platforms, the audit runs when `harness-everything` or `environment-detection`'s Discover phase loads. Only Claude Code has a hook system with exit-code-based blocking; every other platform below gets **advisory text only**, with the same protection level as the "Prompt-Only" column in the README's own comparison table. There is no `preflight.js` audit, no `Rule of 3` circuit breaker, and no WAL on those platforms — nothing runs the `.claude/harness-everything/state/*` runtime-state scripts unless Claude Code (or another hook-capable tool) is also driving the same repo.
+### 2. OpenCode — plugin enforcement, live loading still unverified
 
-**Placement rule:** a platform's own native file/folder (`.claude/settings.json`, `.cursorrules`, `.cursor/skills/`, …) is never moved — it lives exactly where that platform expects it. Anything Harness itself needs that has no native home converges into one exclusively-owned subfolder per platform: `<platform-dir>/harness-everything/`. Nothing else ever creates a directory literally named `harness-everything`, which is what lets the installer add or remove it as a unit — including on uninstall — without touching anything else already in that platform's directory (another tool's files, or skills the user installed by hand).
+`opencode-plugin/` maps supported enforcement behavior to OpenCode's real plugin API. Source-level/mechanism tests exist, but live plugin loading remains unverified; do not promote source/mechanism evidence into a live-host enforcement claim until a real OpenCode session artifact exists.
 
-**Runtime state vs. installed skill content:** `<platform-dir>/harness-everything/` holds runtime state (pure runtime state: hook JSON, circuit-breaker counters, handoff/verification timestamps) kept apart in the `state/` subfolder. On the other hand, the actual installed skills go to each platform's native/expected skills directories (e.g., `.claude/skills/` for Claude, `.cursor/skills/` for Cursor, `.github/skills/` for Copilot, `.codex/skills/` for Codex, `.continue/skills/` for Continue, and `~/.agents/skills/` or `~/.claude/skills/` for Global scope) where they are dynamically discovered and processed. A `manifest.json` under `<platform-dir>/harness-everything/` (or global home) records exactly what the installer put where, per platform, so uninstall can match against the manifest files and perform precise cleanup without guessing. Both runtime state and skills directories are ignored via `.git/info/exclude` (local-only; the working tree's `.gitignore` is never modified), recorded by the installer at install time and removed by the uninstaller.
+### 3. Cursor — skills plus advisory rules
 
-Claude's named Fable agents are copied to `.claude/agents/` (or `~/.claude/agents/` globally) so standalone installs expose the same agents as the plugin manifest. Agent files are tracked in the platform manifest; conflicting user-owned files are preserved and cause the model selector to report an explicit fallback.
+The current installer uses `.cursor/skills/` plus `.cursorrules`. Cursor’s documented skill and plugin surfaces are separate from Harness runtime hooks; routing/verification/retry boundaries remain self-directed unless a compatible mechanism is independently verified.
 
-### 1. Claude Code (hook-enforced)
-Our installer configures native lifecycle hooks inside `.claude/settings.json`, and places project-level skills inside the native `.claude/skills/` directory where Claude Code natively auto-discovers and registers them.
-*   `SessionStart`: Runs `bootstrap.js` to restore previous handoffs, check environment variables, and initialize session state.
-*   `PreToolUse`: Triggers `rule-of-3.js`, `boundary-guard.js`, `depth-guard.js`, `context-compact.js`, and `subagent-scope-guard.js` to intercept tool invocations before they run, and can actually block one (`exit(2)`) — e.g. the Rule of 3 circuit breaker.
-*   `PostToolUse`: Records tool outcomes, updates the persistent transaction log (WAL) via `state-persist.js`, tracks repeat failures, and can only add advisory context back (the tool already ran; nothing here blocks it).
-*   `Stop`: Runs `stop-gate.js` — when a turn ends with uncommitted edits that were never followed by a successful verification command (test/build/lint), it bounces the stop back once per edit batch. This is the mechanical form of `verification-loop`'s pre-delivery gate; on every other platform that gate remains advisory prose.
+### 4. GitHub Copilot agent surfaces — skills plus advisory instructions
 
-### 2. Cursor (advisory only)
-The installer appends guidance to `.cursorrules`. Cursor has no hook/execution mechanism, so nothing in `.claude/harness-everything/state/` gets read or written by Cursor itself, and no tool call can be blocked — the model is simply asked (in the same file, every session) to self-regulate: discover the environment before acting, stop after 3 repeated failures instead of continuing to retry, and prefer small commits.
+The current installer uses `.github/skills/` plus `.github/copilot-instructions.md`. GitHub’s Agent Skills paths are documented, but no Harness-specific plugin or live session is verified here.
 
-### 3. Copilot Chat (advisory only)
-Same mechanism and same limits as Cursor, via `.github/copilot-instructions.md`.
+### 5. Codex — local OpenAI plugin plus advisory installer path
 
-### 4. Codex (advisory only)
-Same mechanism and same limits again, via `AGENTS.md` — Codex's actual custom-instruction file, read automatically at session start (`.codex/config.toml` controls CLI/sandbox behavior, not prompt content, and was never a valid target for this).
+Codex has two distinct Harness integration surfaces and documentation must keep them separate:
 
-### 5. Continue.dev (advisory only)
-Continue's rules system reads individual Markdown files (with YAML frontmatter — `name`, `globs`, `alwaysApply`) from a `.continue/rules/` folder rather than one shared file, so the installer writes a dedicated `.continue/rules/harness.md` with `alwaysApply: true` instead of appending into an arbitrary pre-existing file. No hook/execution mechanism, same limits as Cursor. Global scope writes to `~/.continue/rules/harness.md`.
+- The general `--codex` installer path writes Codex-facing skills/instructions such as `AGENTS.md`; where the host only consumes those instructions, that path is advisory.
+- The packaged local OpenAI plugin under `plugins/harness-everything/` includes `.codex-plugin/plugin.json`, all 26 canonical skills, and lifecycle hooks for `SessionStart`, `UserPromptSubmit`, supported local `PreToolUse` / `PostToolUse`, `SubagentStart` / `SubagentStop`, and `Stop`. Those hooks inject the compact session policy, run the invariant-first kernel, track supported edits and verification, and surface subagent scope changes.
 
-### 6. Hermes Agent (advisory only)
-[Hermes](https://hermes-agent.nousresearch.com/) (Nous Research) auto-injects project context into its system prompt from `.hermes.md`, `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` if present in the directory it's launched from (truncated at ~20k chars) — meaning a Codex or Cursor install already reaches Hermes for free. The installer still writes a dedicated `.hermes.md` for explicit coverage. No hook/execution mechanism. Project scope only: Hermes has no documented global project-instructions equivalent (its own settings live under `~/.hermes/`, which governs model/terminal/skills config, not per-project behavior text), so `--global --hermes` is a deliberate no-op rather than a guess.
+The local plugin therefore has **mechanism-tested local enforcement** for the packaged event/tool mappings. This is package evidence, not a live-host claim; the host's hook review/trust flow and a fresh session are still required. Do not infer broader Claude parity for events or tools that are not listed in the package.
+
+The public OpenAI **Skills-only** submission is narrower again: it ships reusable skills and referenced assets, not the local `.codex-plugin` lifecycle hooks. Public reviewer/listing claims must describe skill/workflow behavior rather than local hook enforcement. See [openai-plugin.md](openai-plugin.md).
+
+### 6. Continue.dev — rules documented, skill discovery unknown
+
+The installer writes `.continue/rules/harness.md` with the platform's native rules format and retains `.continue/skills/` as an adapter candidate. The reviewed official Continue documentation does not establish standalone `SKILL.md` discovery, so no skill-loading or hard-gate parity is claimed.
+
+### 7. Hermes Agent — trusted skills plus advisory context
+
+The installer writes `.hermes.md` for explicit project coverage and can install trusted project skills under `.agents/skills/` plus global skills under `~/.hermes/skills/`. Project skill loading remains subject to Hermes trust; no hard-gate parity is claimed.
+
+---
+
+## Cognitive OS and Skill Mesh
+
+The Cognitive OS is a policy layer, not a parent skill that every domain skill must call.
+
+```mermaid
+flowchart LR
+    D[Discover] --> T[Think]
+    T --> Y[Try]
+    Y --> S[Summarize]
+    S --> R[Record]
+    S -- insufficient evidence --> T
+    Y -- same failure x3 --> Z[Zoom Out]
+    Z --> T
+```
+
+A domain skill may have its own lifecycle — for example RED/GREEN/REFACTOR inside `tdd` — without being forced into a global sequence. The only shared obligations are the kernel invariants.
+
+This separation solves the peer-skill routing problem: a strong host may correctly decide that a task primarily needs `tdd` or `security-review`; that choice is allowed. What it cannot silently erase is the routing/evidence/retry contract established by the runtime.
 
 ---
 
 ## Security Model & Data Locality
 
-Harness runs with a **zero-trust, fully local security model**:
+Harness runs with a local-first, zero-trust model:
+
+1. **No Harness telemetry:** runtime scripts do not upload project code or state as a Harness service.
+2. **Credential protection:** scripts do not require storing user secrets; interactive credentials remain human-controlled.
+3. **Small hook surface:** hook scripts are local Node.js programs and should stay fast and auditable.
+4. **Explicit enforcement labels:** unsupported/advisory behavior must not be documented as hard enforcement.
+5. **Deterministic regression:** mechanism and routing behavior is tested with executable CI gates rather than inferred from documentation.
+
+---
+
+## Validation Boundary
+
+Static configuration is not enough to claim that a host behaves correctly. Validation is layered:
+
+- syntax/reference/manifest checks prove package integrity,
+- `ci/invariant-routing.test.js` proves the kernel contract and documentation invariants,
+- `ci/doc-capability-consistency.test.js` prevents current platform capability claims from drifting apart,
+- mechanism tests prove supported hook/plugin behavior,
+- live host sessions are required before promoting a source/mechanism-tested adapter to live host enforcement.
 
-1. **No External APIs:** Harness does not send telemetry, code snippets, or configuration files to external servers. All processing is done locally via native Node.js scripts.
-2. **Credential Protection:** Harness never asks for or stores API keys or secrets. If any terminal command prompts for a password, Harness's rules immediately direct the model to halt and request manual entry by the human partner.
-3. **Execution Gating:** The hook scripts are written in standard CommonJS, ensuring they compile and run fast (<200ms) to prevent blocking terminal operations.
+The architecture and its Mermaid diagrams are part of that contract. Runtime changes that alter orchestration must update these documents in the same change.