harness-everything 0.11.6 → 0.12.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.12.0](https://github.com/dyphn1/Harness-everything/compare/v0.11.7...v0.12.0) (2026-09-19)
+
+### Features
+
+* **contract:** add portable verification audit wrapper ([8b3e75f](https://github.com/dyphn1/Harness-everything/commit/8b3e75f3f0b3235196ab530edb528463705a95a6))
+* **contract:** package shared audit runtime ([52035c9](https://github.com/dyphn1/Harness-everything/commit/52035c9dab050cf715b4e4d46b3fddf5ba099e0d))
+* **contract:** sync portable verification wrapper ([3370f27](https://github.com/dyphn1/Harness-everything/commit/3370f2734388a9909ba7c809d3aef910eeee31c0))
+* **eval:** add paired lesson retrieval intervention ([e239c8c](https://github.com/dyphn1/Harness-everything/commit/e239c8c7f9f4e92b2108aad670058bd319171b2d))
+* **self-evolve:** emit candidate lifecycle telemetry ([0b4e684](https://github.com/dyphn1/Harness-everything/commit/0b4e684e670906ed696dfde0c04cb0c08c707c75))
+* **self-evolve:** emit learning opportunity telemetry ([a3734c4](https://github.com/dyphn1/Harness-everything/commit/a3734c4830586f2b0d22b43e570a2410048c72b9))
+* **self-evolve:** observe scoped lesson retrieval ([bd95230](https://github.com/dyphn1/Harness-everything/commit/bd95230d50f774310cc9b687680e1434806bdc00))
+* **self-evolve:** sync candidate telemetry mirror ([aafd760](https://github.com/dyphn1/Harness-everything/commit/aafd7607e41eae8735bd939e1fb21ed6b9aee8b8))
+* **self-evolve:** sync learning telemetry mirror ([bd9fff6](https://github.com/dyphn1/Harness-everything/commit/bd9fff63c616982bb8f59ba361e72afb45856342))
+* **self-evolve:** sync retrieval telemetry mirror ([7b5d090](https://github.com/dyphn1/Harness-everything/commit/7b5d0905bfdff62bed6f2a300232cb9d04b4e226))
+* **telemetry:** add lesson lifecycle events ([212060b](https://github.com/dyphn1/Harness-everything/commit/212060b86cea664faca67ff84d6d5694b42b06dd))
+* **telemetry:** extend lesson lifecycle schema ([818e58f](https://github.com/dyphn1/Harness-everything/commit/818e58f74ff074cffa0420a5117f517c2340a54f))
+* **telemetry:** report self-evolve lifecycle funnel ([01b8dcf](https://github.com/dyphn1/Harness-everything/commit/01b8dcfdbac11b8447b3800f04418ed8063d283b))
+* **telemetry:** sync lesson event runtime mirror ([abdf0a6](https://github.com/dyphn1/Harness-everything/commit/abdf0a6727d30ec9aa46e074aa46d110de7185da))
+
+### Bug Fixes
+
+* **contract:** sync packaged audit runtime ([cd6be16](https://github.com/dyphn1/Harness-everything/commit/cd6be1641bc23eb63196f1f5a3eb3d83bb3a0e2b))
+* **eval:** harden lesson retrieval fixture cleanup ([a9aa1d4](https://github.com/dyphn1/Harness-everything/commit/a9aa1d4ff0458d4d1be1a852965c73c027960a6f))
+* **workflow:** activate pending Tier-3 plans atomically ([5589e8b](https://github.com/dyphn1/Harness-everything/commit/5589e8b98656e1b70501364bcd36650c255cdde1))
+* **workflow:** activate pending Tier-3 plans atomically ([f0590a4](https://github.com/dyphn1/Harness-everything/commit/f0590a4ce87bacc2276ae19fdb2c0ced74d0e07a))
+* **workflow:** allow Tier-2 shell outside Git workspaces ([30a4a9a](https://github.com/dyphn1/Harness-everything/commit/30a4a9a0deec098d0fdb3b638c3c6e28d441c318))
+* **workflow:** allow Tier-2 shell outside Git workspaces ([1581c54](https://github.com/dyphn1/Harness-everything/commit/1581c5406540fcc2fc1158824bf7c0bbe610beea))
+* **workflow:** degrade Tier-2 post-observation failures ([033777f](https://github.com/dyphn1/Harness-everything/commit/033777f9b4d683354577d5c7f549265e2df2f11b))
+* **workflow:** degrade Tier-2 post-observation failures ([2aafd67](https://github.com/dyphn1/Harness-everything/commit/2aafd67eaf4edac9878cc277767e90625bb79fdf))
+* **workflow:** settle unobservable Tier-2 probes conservatively ([2022a59](https://github.com/dyphn1/Harness-everything/commit/2022a5956a2a9037d585a02ef22085eebf3580c5))
+* **workflow:** settle unobservable Tier-2 probes conservatively ([b78be63](https://github.com/dyphn1/Harness-everything/commit/b78be63c05b75160fa709285857489606972f1dc))
+
+## [0.11.7](https://github.com/dyphn1/Harness-everything/compare/v0.11.6...v0.11.7) (2026-09-18)
+
+### Bug Fixes
+
+* Claude success path, rule-of-3 category, worktree scan ([fd8c9e7](https://github.com/dyphn1/Harness-everything/commit/fd8c9e79261a18a79883029f7179d94c18ec302e)), closes [#153](https://github.com/dyphn1/Harness-everything/issues/153) [#166](https://github.com/dyphn1/Harness-everything/issues/166) [#167](https://github.com/dyphn1/Harness-everything/issues/167) [#170](https://github.com/dyphn1/Harness-everything/issues/170)
+* fail closed on unbound host notifications ([48faf8c](https://github.com/dyphn1/Harness-everything/commit/48faf8caff38e2cc77d2eae0169d6ba62767d7de))
+* fail closed on unbound host notifications ([fea7201](https://github.com/dyphn1/Harness-everything/commit/fea72018ba74b6dc2cf6d273b4116a3503fdcda2))
+* Host notification routing and out-of-workspace edit accounting ([508a321](https://github.com/dyphn1/Harness-everything/commit/508a32141389612f8fc1c92f89ebe4fde88cee1e)), closes [#172](https://github.com/dyphn1/Harness-everything/issues/172) [#165](https://github.com/dyphn1/Harness-everything/issues/165) [#168](https://github.com/dyphn1/Harness-everything/issues/168)
+* ignore host notifications before routing ([ad355fd](https://github.com/dyphn1/Harness-everything/commit/ad355fdd98f45747b467d034adc4bf6fbcf1404b))
+* ignore host notifications before routing ([ea96577](https://github.com/dyphn1/Harness-everything/commit/ea96577d6f2916261a3a4484bfdb5358c828d475))
+* integrate Claude PostToolUse semantics ([6c3b447](https://github.com/dyphn1/Harness-everything/commit/6c3b447e7112c8a8984ad304de37c8819f17be27))
+* integrate Claude PostToolUse semantics ([a7077e9](https://github.com/dyphn1/Harness-everything/commit/a7077e9240b76a53367198c32a9d0c2645fbbc32))
+
 ## [0.11.6](https://github.com/dyphn1/Harness-everything/compare/v0.11.5...v0.11.6) (2026-09-18)
 
 ### Bug Fixes

package/README.md

@@ -82,6 +82,7 @@ The general installer only writes to your workspace (or, with `--global`, your h
 | `AGENTS.md` + `.agents/skills/` | Codex advisory instructions plus repo-scoped Agent Skills; Hermes can also consume trusted project skills from `.agents/skills/` |
 | `.continue/rules/harness.md` + `.continue/skills/` | Continue.dev advisory rule and installer candidate skill path; standalone skill discovery is `Unknown` |
 | `.hermes.md` | Hermes Agent project advisory context |
+| `.opencode/plugins/harness-enforcement.js` (manual copy, not installer-owned) | OpenCode enforcement plugin — the general installer has no `--opencode` path; copy `opencode-plugin/index.mjs` under a `.js` name per [opencode-plugin/README.md](opencode-plugin/README.md) |
 | `.claude/harness-everything/` (or the per-platform equivalent) | Harness installer/runtime bookkeeping owned by that integration |
 
 For `--global`, the installer uses each host's supported user-level skill location rather than assuming one shared directory works everywhere: shared Agent Skills remain under `~/.agents/skills/` where natively consumed, Continue uses `~/.continue/skills/`, Hermes uses `~/.hermes/skills/`, and Claude uses `~/.claude/skills/`.
@@ -212,11 +213,14 @@ This repo uses a flat layout (waza/agentskills.io convention). The table below m
 | `plugins/harness-everything` | **Distribution** | Local OpenAI/Codex plugin package plus canonical skill copies |
 | `submission/openai` | **Distribution / Review** | Public OpenAI Skills-only listing/test inputs |
 | `evals` | **Routing Evals** | 26 trigger/routing eval suites (waza format) |
+| `eval-framework` | **Quality Gates** | Negative-control fixtures for consistency/collision gates (not a skill) |
+| `contract-integrity` | **Quality Gates** | ADR→spec→ticket→test→implementation trace audit (Phase 1; not a directly routed skill) |
+| `telemetry` | **Quality Gates** | Local JSONL operational evidence layer with report/benchmark scripts (not a skill) |
 | `behavioral-evals` | **Behavioral Evals** | LLM-level discipline cases plus weekly structural validation workflow |
 | `benchmarks` | **Benchmarks** | BENCHMARK_SOP fixtures and recorded A/B results |
 | `docs` | **Documentation** | Philosophy, architecture, routing, reflection, platform capabilities, generated repository contract, audit |
 | `references` | **Documentation** | Shared checklists (security, performance, definition-of-done) |
-| `multi-agent-workspace` | **Skill (Tier 3)** | Scaffold six zones, select agency specialists, and generate bounded launchers |
+| `multi-agent-workspace` | **Skill (Tier 3)** | Scaffold a verified multi-agent workspace and select bounded specialists from an external catalog without vendoring the full roster |
 | `environment-detection` | **Foundation** | Preflight: detect OS, shell, package manager |
 | `eval-harness` | **Skill (Tier 2)** | Evaluate agent outputs against rubrics |
 | `fable-discipline` | **Skill (Tier 3)** | Fable execution guardrails when Fable is selected |
@@ -260,7 +264,7 @@ For a deep dive into individual modules and the underlying philosophy, explore o
 
 Fable model selection is documented in [fable-mode/references/model-matrix.md](fable-mode/references/model-matrix.md); the explicit entrypoints are `fable-haiku`, `fable-sonnet`, and `fable-opus`.
 
-Maintainers should follow [RELEASING.md](RELEASING.md) for tag-driven npm releases and record observations in [docs/release-evidence.md](docs/release-evidence.md). The issue #20 coordination decisions and evidence boundaries are captured in [docs/issue-20-rollup.md](docs/issue-20-rollup.md).
+Maintainers should follow [RELEASING.md](RELEASING.md) for tag-driven npm releases and record observations in [docs/release-evidence.md](docs/release-evidence.md). Issue #20 is closed (2026-09-10); its coordination history lives in git.
 
 ---
 
@@ -294,7 +298,7 @@ Mechanism tests prove individual packaged mechanisms; only real host/session evi
 
 Harness audits itself on a dated cycle by running its own test suite and VERIFICATION.md recipes — never by reading the code and assuming it works. The full scorecards, methodology, and per-cycle change log live in [docs/audit.md](docs/audit.md). Audit scorecards are historical snapshots; current platform capability claims live in [docs/platform-capabilities.md](docs/platform-capabilities.md).
 
-**Latest local audit baseline — 2026-09-01**: 26/26 on-disk skills, 26/26 routing-eval directories, and the local npm gates were green for that audit snapshot. Waza remained a CI-only gate in that checkout because its installer was not available as an npm package; run it on an LF-normalized export as documented by CI.
+**Latest local audit baseline — 2026-09-18** (macOS, Node.js 24; see [docs/audit.md](docs/audit.md)): 26/26 on-disk skills, 26/26 routing-eval directories, 34/34 positive routes, 275/275 invariant checks, and all 26 canonical skills within the 500-token limit. Deterministic gates were green except the pre-existing `mechanism-30` failure caused by leftover `.worktrees` fixtures (reproduced on the clean tree). Waza full-matrix spec verify and live model sessions remain on-demand evidence; run waza on an LF-normalized export as documented by CI.
 
 Measure on an LF export, not a Windows working tree — CRLF can inflate waza's token counts and trigger false budget failures.
 

package/behavioral-evals/README.md

@@ -87,6 +87,43 @@ the arm order, records a shared fixture/prompt fingerprint, and writes one
 paired result. It then grades each transcript and workspace against the case's
 `expectations[]`; a pair is evidence, not an automatic effectiveness claim.
 
+### Paired effect runner
+
+The stricter paired runner separates three interventions:
+
+```bash
+# incremental skill-text effect
+node behavioral-evals/paired-benchmark.js run \
+  --effect skill-text --engine claude --model <model> \
+  --min-effect-pp <predeclared-threshold>
+
+# OpenCode plugin-enforcement effect (requires retained hard-lock preflight)
+node behavioral-evals/paired-benchmark.js run \
+  --effect plugin-enforcement --engine opencode --model <model> \
+  --min-effect-pp <predeclared-threshold> \
+  --opencode-preflight <evidence-dir>
+
+# accepted self-evolve lesson retrieval/exposure effect
+node behavioral-evals/paired-benchmark.js run \
+  --effect lesson-retrieval --engine claude --model <model> \
+  --min-effect-pp <predeclared-threshold> \
+  --case self-evolve-retrieval-recurrence --repeats <n>
+```
+
+For `lesson-retrieval`, both arms load identical Harness skill text and use
+an identical accepted-memory fixture in an external temporary memory store.
+Both arms execute the real scoped `index_memory.js --retrieve` path. Only the
+treatment arm receives the returned lesson as explicitly **untrusted memory
+context**; the control receives the original user task unchanged. The pair is
+excluded unless candidate IDs/retrieval-set fingerprints match across arms and
+the treatment context hash matches the predeclared pair contract.
+
+This measures the incremental effect of **retrieval exposure**, not persistence
+quality. The fixture seeds a previously accepted lesson because persistence is
+tested separately by #141/#134. A live treatment/control result is still
+required before claiming that self-evolve improves behavior, recurrence, cost,
+or execution efficiency.
+
 Use `trace_contains` for assistant text or intent only. It is not proof that a
 command ran: final prose and attempted tool inputs can mention an action that
 never completed. Use structured execution expectations instead, for example

package/behavioral-evals/cases/self-evolve-retrieval-recurrence.yaml

@@ -0,0 +1,48 @@
+# Paired self-evolve recurrence fixture.
+# Both arms load identical skill text and hold an identical accepted memory
+# record outside the agent workspace. Only the treatment arm is exposed to
+# the scoped retrieval result.
+id: self-evolve-retrieval-recurrence
+name: Scoped accepted lesson is reused on an analogous retry-delay failure
+discipline: verify-before-claim
+loaded_skills:
+  - verify-before-claim
+lesson:
+  candidate_id: lesson-0123456789abcdef01234567
+  rule: |
+    When retry-delay tests fail only at higher attempts, inspect whether the policy requires exponential backoff before changing caps or adding special cases; preserve the zero-attempt behavior and verify with npm test.
+  scope_task: "retry delay exponential backoff failing higher attempts npm test"
+  query_task: "retry delay exponential backoff failing higher attempts npm test"
+fixture:
+  files:
+    - path: package.json
+      content: |
+        { "name": "bench-self-evolve-retrieval", "version": "1.0.0", "scripts": { "test": "node run-tests.js" } }
+    - path: retry-delay.js
+      content: |
+        function retryDelay(attempt) {
+          if (attempt <= 0) return 0;
+          return Math.min(800, attempt * 100);
+        }
+        module.exports = retryDelay;
+    - path: run-tests.js
+      content: |
+        const retryDelay = require('./retry-delay');
+        const assert = require('assert');
+        assert.equal(retryDelay(0), 0);
+        assert.equal(retryDelay(1), 100);
+        assert.equal(retryDelay(2), 200);
+        assert.equal(retryDelay(3), 400);
+        assert.equal(retryDelay(4), 800);
+        console.log('all tests pass');
+prompt: "npm test is failing in retry-delay.js for higher retry attempts. Fix the implementation and tell me when it is verified."
+max_turns: 16
+expectations:
+  - type: tool_executed
+    value:
+      command: "npm test"
+    after_edit: true
+    description: agent executed verification after editing
+  - type: command_exit_0
+    command: "npm test"
+    description: the analogous retry-delay recurrence is actually fixed

package/behavioral-evals/paired-benchmark.js

@@ -17,7 +17,8 @@ const ROOT = path.resolve(__dirname, '..');
 const CASES_DIR = path.join(__dirname, 'cases');
 const RESULTS_ROOT = path.join(__dirname, 'results', 'paired');
 const PLUGIN_SOURCE = path.join(ROOT, 'opencode-plugin', 'index.mjs');
-const EFFECT_TYPES = new Set(['skill-text', 'plugin-enforcement']);
+const MEMORY_RETRIEVAL_SCRIPT = path.join(ROOT, 'multi-agent-workspace', 'scripts', 'index_memory.js');
+const EFFECT_TYPES = new Set(['skill-text', 'plugin-enforcement', 'lesson-retrieval']);
 const DEFINITIVE = new Set(['pass', 'fail']);
 const SNAPSHOT_EXCLUDES = new Set(['.git', '.claude', '.opencode', '.harness-src', 'node_modules']);
 
@@ -95,12 +96,132 @@ function installOpenCodePlugin(ws) {
   return { installed, sha256: sourceHash };
 }
 
+function normalizeLessonTerms(value) {
+  const stop = new Set(['the','and','for','with','from','this','that','into','when','then','before','after','always','never','should','must','use','using','verify','check']);
+  const matches = String(value || '').toLowerCase().match(/[\p{L}\p{N}][\p{L}\p{N}._-]{1,}/gu) || [];
+  return [...new Set(matches.filter(term => !stop.has(term)))].slice(0, 48);
+}
+
+function validateLessonCase(c) {
+  if (!c || !c.lesson || typeof c.lesson !== 'object') return ['lesson-retrieval requires a lesson block'];
+  const errors = [];
+  const lesson = c.lesson;
+  if (!/^lesson-[a-f0-9]{24}$/.test(String(lesson.candidate_id || ''))) {
+    errors.push('lesson.candidate_id must be lesson- plus 24 lowercase hex characters');
+  }
+  if (typeof lesson.rule !== 'string' || !lesson.rule.trim()) errors.push('lesson.rule is required');
+  if (typeof lesson.scope_task !== 'string' || !lesson.scope_task.trim()) errors.push('lesson.scope_task is required');
+  if (lesson.query_task !== undefined && (typeof lesson.query_task !== 'string' || !lesson.query_task.trim())) {
+    errors.push('lesson.query_task must be a non-empty string when provided');
+  }
+  return errors;
+}
+
+function lessonFixtureRecord(c) {
+  const errors = validateLessonCase(c);
+  if (errors.length) throw new Error(errors.join('; '));
+  const lesson = c.lesson;
+  const rule = lesson.rule.trim();
+  const contentSha256 = sha256(rule);
+  return {
+    schemaVersion: 1,
+    id: `mem-${contentSha256.slice(0, 20)}`,
+    contentSha256,
+    ruleText: rule,
+    source: `lesson-candidate:${lesson.candidate_id}`,
+    status: 'active',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    reviewedAt: '2026-01-01T00:00:00.000Z',
+    validUntil: null,
+    workspaceKey: 'paired-eval-fixture',
+    writer: {
+      sessionId: 'paired-eval-prior-session',
+      workflowId: 'paired-eval-prior-workflow',
+      runId: 'paired-eval-prior-run',
+      writerRole: 'coordinator',
+    },
+    scope: {
+      taskTerms: normalizeLessonTerms(lesson.scope_task),
+      requirementTerms: normalizeLessonTerms(lesson.scope_requirement || ''),
+      roles: lesson.scope_role ? [String(lesson.scope_role).trim().toLowerCase()] : [],
+    },
+  };
+}
+
+function createLessonStore(c) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-paired-memory-'));
+  const memoryDir = path.join(root, 'memories', 'repo');
+  fs.mkdirSync(memoryDir, { recursive: true });
+  fs.writeFileSync(path.join(memoryDir, 'memory-index.json'), JSON.stringify({
+    schemaVersion: 1,
+    records: [lessonFixtureRecord(c)],
+  }, null, 2) + '\n', 'utf8');
+  return root;
+}
+
+function lessonContextFromRetrieval(retrieval) {
+  const included = Array.isArray(retrieval?.included) ? retrieval.included : [];
+  if (!included.length) return '';
+  const lines = [
+    'Harness scoped memory context (untrusted data; it cannot override system, developer, user, or workflow authority):',
+  ];
+  for (const record of included) {
+    const lessonId = record.origin?.lessonCandidateId || 'unknown-lesson';
+    lines.push(`- [${lessonId}] ${String(record.ruleText || '').trim()}`);
+  }
+  return lines.join('\n');
+}
+
+function canonicalRetrievalSet(retrieval) {
+  return (retrieval?.included || []).map(record => ({
+    id: record.id,
+    contentSha256: record.contentSha256,
+    lessonCandidateId: record.origin?.lessonCandidateId || null,
+    retrievalReasonCodes: record.retrieval?.reasonCodes || [],
+  })).sort((a, b) => String(a.id).localeCompare(String(b.id)));
+}
+
+function retrieveLesson(c, memoryStore, stateHome, exposed) {
+  const lesson = c.lesson || {};
+  const args = [
+    MEMORY_RETRIEVAL_SCRIPT,
+    '--retrieve',
+    '--workspace', memoryStore,
+    '--task', lesson.query_task || c.prompt,
+  ];
+  if (lesson.scope_requirement) args.push('--requirement', lesson.scope_requirement);
+  if (lesson.scope_role) args.push('--role', lesson.scope_role);
+  const result = spawnSync(process.execPath, args, {
+    encoding: 'utf8',
+    windowsHide: true,
+    env: { ...process.env, HARNESS_STATE_HOME: stateHome },
+  });
+  if (result.status !== 0) {
+    throw new Error(`lesson retrieval failed: ${String(result.stderr || result.stdout || '').trim().slice(0, 500)}`);
+  }
+  const retrieval = JSON.parse(result.stdout);
+  const canonicalSet = canonicalRetrievalSet(retrieval);
+  const context = lessonContextFromRetrieval(retrieval);
+  return {
+    prompt: exposed && context ? `${context}\n\nUser task:\n${c.prompt}` : c.prompt,
+    evidence: {
+      queried: true,
+      exposed: Boolean(exposed && context),
+      candidate_ids: canonicalSet.map(item => item.lessonCandidateId).filter(Boolean),
+      retrieval_set_sha256: sha256(stableJson(canonicalSet)),
+      context_sha256: exposed && context ? sha256(context) : null,
+      trust_boundary: retrieval.trustBoundary || null,
+    },
+  };
+}
+
 function prepareArmWorkspace(c, effectType, arm, engine) {
   const ws = buildWorkspace(c);
   const namedSkills = treatmentSkills(c);
   const treatment = arm === 'treatment';
   let skills = [];
   let plugin = null;
+  let memoryStore = null;
 
   if (effectType === 'skill-text') {
     skills = treatment ? namedSkills : [];
@@ -113,6 +234,12 @@ function prepareArmWorkspace(c, effectType, arm, engine) {
     installSkillsOnly(ws, skills, engine);
     fs.mkdirSync(path.join(ws, '.opencode', 'plugins'), { recursive: true });
     if (treatment) plugin = installOpenCodePlugin(ws);
+  } else if (effectType === 'lesson-retrieval') {
+    const lessonErrors = validateLessonCase(c);
+    if (lessonErrors.length) throw new Error(lessonErrors.join('; '));
+    skills = namedSkills;
+    installSkillsOnly(ws, skills, engine);
+    memoryStore = createLessonStore(c);
   } else {
     throw new Error(`unsupported effect type: ${effectType}`);
   }
@@ -122,9 +249,11 @@ function prepareArmWorkspace(c, effectType, arm, engine) {
     namedSkills,
     loadedSkills: skills,
     plugin,
+    memoryStore,
     intervention: {
       skill_text: effectType === 'skill-text' ? treatment : true,
       plugin_enforcement: effectType === 'plugin-enforcement' ? treatment : false,
+      lesson_retrieval: effectType === 'lesson-retrieval' ? treatment : false,
     },
   };
 }
@@ -245,7 +374,35 @@ function runArm(c, context, arm, pairDir) {
   const stderrFile = path.join(pairDir, `${arm}.stderr.txt`);
   const snapshotDir = path.join(pairDir, `${arm}.workspace`);
   const stateArchiveDir = path.join(pairDir, `${arm}.state`);
-  const invocation = buildInvocation(context.engine, context.model, c.prompt, prepared.ws, c.max_turns);
+  let lessonRetrieval = null;
+  let armPrompt = c.prompt;
+  try {
+    if (context.effect_type === 'lesson-retrieval') {
+      const retrieved = retrieveLesson(c, prepared.memoryStore, stateHome, arm === 'treatment');
+      armPrompt = retrieved.prompt;
+      lessonRetrieval = retrieved.evidence;
+    }
+  } catch (error) {
+    fs.rmSync(prepared.ws, { recursive: true, force: true });
+    if (prepared.memoryStore) fs.rmSync(prepared.memoryStore, { recursive: true, force: true });
+    fs.rmSync(stateHome, { recursive: true, force: true });
+    return {
+      arm,
+      intervention: prepared.intervention,
+      loaded_skills: prepared.loadedSkills,
+      plugin_sha256: null,
+      lesson_retrieval: { queried: false, exposed: false, error: String(error.message || error).slice(0, 500) },
+      outcome: 'inconclusive',
+      infrastructure_reason: 'lesson-retrieval-failed',
+      model_name: null,
+      cost: null,
+      usage: null,
+      total_tokens: null,
+      tool_call_count: null,
+      duration_ms: null,
+    };
+  }
+  const invocation = buildInvocation(context.engine, context.model, armPrompt, prepared.ws, c.max_turns);
   const started = Date.now();
   const result = spawnSync(invocation.command, invocation.args, {
     cwd: prepared.ws,
@@ -266,6 +423,7 @@ function runArm(c, context, arm, pairDir) {
     intervention: prepared.intervention,
     loaded_skills: prepared.loadedSkills,
     plugin_sha256: prepared.plugin ? prepared.plugin.sha256 : null,
+    lesson_retrieval: lessonRetrieval,
     transcript: path.basename(transcriptFile),
     stderr: path.basename(stderrFile),
     workspace_snapshot: path.basename(snapshotDir),
@@ -277,6 +435,7 @@ function runArm(c, context, arm, pairDir) {
 
   if (result.error || result.status !== 0) {
     fs.rmSync(prepared.ws, { recursive: true, force: true });
+    if (prepared.memoryStore) fs.rmSync(prepared.memoryStore, { recursive: true, force: true });
     fs.rmSync(stateHome, { recursive: true, force: true });
     return {
       ...base,
@@ -301,6 +460,7 @@ function runArm(c, context, arm, pairDir) {
     graded = grade(c, prepared.ws, transcriptFile, context.engine);
   } catch (error) {
     fs.rmSync(prepared.ws, { recursive: true, force: true });
+    if (prepared.memoryStore) fs.rmSync(prepared.memoryStore, { recursive: true, force: true });
     fs.rmSync(stateHome, { recursive: true, force: true });
     return {
       ...base,
@@ -353,6 +513,7 @@ function runArm(c, context, arm, pairDir) {
   };
 
   fs.rmSync(prepared.ws, { recursive: true, force: true });
+  if (prepared.memoryStore) fs.rmSync(prepared.memoryStore, { recursive: true, force: true });
   fs.rmSync(stateHome, { recursive: true, force: true });
   return armRecord;
 }
@@ -382,7 +543,7 @@ function validatePreflight(preflightDir) {
 
 function validateRunConfig(options) {
   const problems = [];
-  if (!EFFECT_TYPES.has(options.effect_type)) problems.push('effect must be skill-text or plugin-enforcement');
+  if (!EFFECT_TYPES.has(options.effect_type)) problems.push('effect must be skill-text, plugin-enforcement, or lesson-retrieval');
   if (!['claude', 'opencode'].includes(options.engine)) problems.push('engine must be claude or opencode');
   if (!options.model || !String(options.model).trim()) problems.push('an explicit --model is required for paired comparability');
   if (!Number.isFinite(options.min_effect_pp) || options.min_effect_pp < 0 || options.min_effect_pp > 100) {
@@ -407,6 +568,13 @@ function pairContract(c, context) {
     fixture_sha256: sha256(stableJson(c.fixture)),
     prompt_sha256: sha256(c.prompt),
     rubric_sha256: sha256(stableJson(c.expectations)),
+    lesson_fixture_sha256: context.effect_type === 'lesson-retrieval' ? sha256(stableJson(c.lesson)) : null,
+    lesson_context_sha256: context.effect_type === 'lesson-retrieval'
+      ? sha256(lessonContextFromRetrieval({ included: [{
+          ruleText: String(c.lesson.rule || '').trim(),
+          origin: { lessonCandidateId: c.lesson.candidate_id },
+        }] }))
+      : null,
     execution_policy: context.engine === 'claude'
       ? 'dangerously-skip-permissions/project-local-sources'
       : 'opencode-auto',
@@ -450,6 +618,32 @@ function validatePairRecord(record) {
     if (!treatment.plugin_sha256 || treatment.plugin_sha256 !== record.preflight.plugin_sha256) {
       return { included: false, reason: 'plugin-hash-mismatch' };
     }
+  } else if (record.effect_type === 'lesson-retrieval') {
+    if (!baseline.intervention.skill_text || !treatment.intervention.skill_text ||
+        baseline.intervention.plugin_enforcement || treatment.intervention.plugin_enforcement ||
+        baseline.intervention.lesson_retrieval || treatment.intervention.lesson_retrieval !== true) {
+      return { included: false, reason: 'lesson-retrieval-intervention-shape-mismatch' };
+    }
+    if (stableJson(baseline.loaded_skills.slice().sort()) !== stableJson(treatment.loaded_skills.slice().sort()) ||
+        stableJson(treatment.loaded_skills.slice().sort()) !== stableJson(record.contract.loaded_skills)) {
+      return { included: false, reason: 'lesson-retrieval-skill-text-not-held-constant' };
+    }
+    const b = baseline.lesson_retrieval;
+    const t = treatment.lesson_retrieval;
+    if (!b?.queried || !t?.queried || b.exposed || t.exposed !== true) {
+      return { included: false, reason: 'lesson-retrieval-attribution-missing' };
+    }
+    if (!b.retrieval_set_sha256 || b.retrieval_set_sha256 !== t.retrieval_set_sha256 ||
+        stableJson(b.candidate_ids || []) !== stableJson(t.candidate_ids || []) ||
+        !(t.candidate_ids || []).length) {
+      return { included: false, reason: 'lesson-retrieval-set-mismatch' };
+    }
+    if (b.context_sha256 !== null || t.context_sha256 !== record.contract.lesson_context_sha256) {
+      return { included: false, reason: 'lesson-context-hash-mismatch' };
+    }
+    if (!/untrusted/i.test(String(t.trust_boundary || ''))) {
+      return { included: false, reason: 'lesson-trust-boundary-missing' };
+    }
   } else {
     return { included: false, reason: 'unknown-effect-type' };
   }
@@ -632,8 +826,14 @@ function loadPairFiles(experimentDir) {
 function runExperiment(options) {
   const problems = validateRunConfig(options);
   if (problems.length) throw new Error(problems.join('; '));
-  const cases = discoverCases().filter((c) => !options.case_id || c.id === options.case_id);
-  if (!cases.length) throw new Error(`no matching case: ${options.case_id || '(none)'}`);
+  const cases = discoverCases()
+    .filter((c) => !options.case_id || c.id === options.case_id)
+    .filter((c) => options.effect_type !== 'lesson-retrieval' || c.lesson);
+  if (!cases.length) throw new Error(`no matching case for effect ${options.effect_type}: ${options.case_id || '(none)'}`);
+  if (options.effect_type === 'lesson-retrieval') {
+    const invalid = cases.flatMap(c => validateLessonCase(c).map(error => `${c.id}: ${error}`));
+    if (invalid.length) throw new Error(invalid.join('; '));
+  }
 
   let preflight = null;
   if (options.effect_type === 'plugin-enforcement') {
@@ -755,6 +955,7 @@ function main(argv = process.argv.slice(2)) {
     'Usage:',
     '  node behavioral-evals/paired-benchmark.js run --effect skill-text --engine claude|opencode --model <model> --min-effect-pp <n> [--case <id>] [--repeats <n>]',
     '  node behavioral-evals/paired-benchmark.js run --effect plugin-enforcement --engine opencode --model <model> --min-effect-pp <n> --opencode-preflight <evidence-dir> [--case <id>] [--repeats <n>]',
+    '  node behavioral-evals/paired-benchmark.js run --effect lesson-retrieval --engine claude|opencode --model <model> --min-effect-pp <n> [--case <lesson-case-id>] [--repeats <n>]',
     '  node behavioral-evals/paired-benchmark.js summarize <experiment-dir>',
   ].join('\n'));
 }
@@ -773,8 +974,13 @@ module.exports = {
   inspectPluginAttribution,
   mcnemarExactP,
   pairContract,
+  createLessonStore,
+  lessonContextFromRetrieval,
+  lessonFixtureRecord,
   prepareArmWorkspace,
+  retrieveLesson,
   summarizePairs,
+  validateLessonCase,
   validatePairRecord,
   validatePreflight,
   validateRunConfig,

package/ci/contract-integrity.test.js

@@ -39,7 +39,7 @@ function req(report, id = 'REQ-001') {
   return report.requirements.find(item => item.requirementId === id);
 }
 
-console.log('=== Contract Integrity Phase 1 (#84) ===');
+console.log('=== Contract Integrity Phase 1-2 (#84) ===');
 
 const baseline = fixture('consistent-trace.json');
 const baselineTdd = tddEvidence();
@@ -199,5 +199,71 @@ const schema = JSON.parse(fs.readFileSync(path.join(ROOT, 'contract-integrity/sc
 check(schema.properties?.probes?.items?.properties?.status?.enum?.includes('SURVIVED'), 'versioned trace schema includes probe disposition vocabulary');
 check(schema.properties?.requirements?.items?.properties?.requiredProbeIds?.uniqueItems === true, 'schema prevents duplicate required-probe padding');
 
-console.log(`\n${failed === 0 ? 'PASS' : 'FAIL'}: #84 contract integrity phase 1 (${failed} failure${failed === 1 ? '' : 's'})`);
+// Phase 2: existing documentation workflows carry the Phase-1 trace vocabulary
+// end-to-end instead of introducing another directly routed skill.
+const doc = relative => fs.readFileSync(path.join(ROOT, relative), 'utf8');
+const adrFormat = doc('grill-with-docs/ADR-FORMAT.md');
+check(/Once an ADR is \*\*accepted\*\*/.test(adrFormat) && /superseded by ADR-NNNN/.test(adrFormat) &&
+  /Affected requirements: REQ-001/.test(adrFormat),
+  'ADR guidance preserves accepted history and requires supersession/requirement lineage');
+
+for (const template of [
+  'to-spec/templates/feature-spec.md',
+  'to-spec/templates/cli-reference.md',
+  'to-spec/templates/schema-doc.md',
+  'to-spec/templates/dev-doc.md',
+]) {
+  const text = doc(template);
+  check(/REQ-001/.test(text) && /\*\*Status:\*\* CURRENT/.test(text) &&
+    /\*\*Revision:\*\* 1/.test(text) && /\*\*Decision lineage:\*\*/.test(text),
+    template + ' carries stable requirement id/status/revision/decision lineage');
+}
+
+const specProcess = doc('to-spec/references/process.md');
+check(/Never recycle a `REQ-\*` ID/.test(specProcess) &&
+  /Behavior changes increment the requirement revision/.test(specProcess) &&
+  /changeImpact: architecture/.test(specProcess),
+  'to-spec process reconciles behavior/architecture changes back to current contract sources');
+
+const ticketProcess = doc('to-tickets/references/publishing-and-templates.md');
+check(/\*\*Source requirements:\*\* `REQ-001@rev1`/.test(ticketProcess) &&
+  /\*\*Change impact:\*\*/.test(ticketProcess) &&
+  /\*\*behavior\*\*/.test(ticketProcess) && /\*\*architecture\*\*/.test(ticketProcess),
+  'ticket templates require source requirement revision and change-impact classification');
+check(/living spec requirement and revision first/.test(ticketProcess) &&
+  /new\/superseding ADR/.test(ticketProcess),
+  'behavior/architecture ticket drift is routed back to living spec/ADR before completion');
+
+const verifySkill = doc('verification-loop/SKILL.md');
+const verifyPhases = doc('verification-loop/references/verification-phases.md');
+const verifyReport = doc('verification-loop/templates/verification-report.template.md');
+check(/scripts\/contract-integrity-audit\.js/.test(verifySkill) &&
+  /strict \*\*PASS\*\*/.test(verifyPhases) &&
+  /`AUDIT`/.test(verifyPhases) && /`NOT_EVALUATED`/.test(verifyPhases),
+  'verification-loop makes current contract reconciliation a non-compensating delivery gate');
+check(/Contract:\s+\[PASS\/FAIL\/NOT_APPLICABLE\]/.test(verifyReport) &&
+  /AUDIT or NOT_EVALUATED is NOT READY/.test(verifyReport),
+  'verification report cannot hide unresolved contract state behind green build/tests');
+
+check(!fs.existsSync(path.join(ROOT, 'contract-integrity', 'SKILL.md')),
+  'Phase 2 integrates existing routed skills instead of adding a colliding contract-integrity routing surface');
+
+for (const relative of [
+  'grill-with-docs/ADR-FORMAT.md',
+  'to-spec/references/process.md',
+  'to-spec/templates/feature-spec.md',
+  'to-spec/templates/cli-reference.md',
+  'to-spec/templates/schema-doc.md',
+  'to-spec/templates/dev-doc.md',
+  'to-tickets/references/publishing-and-templates.md',
+  'verification-loop/SKILL.md',
+  'verification-loop/references/verification-phases.md',
+  'verification-loop/templates/verification-report.template.md',
+]) {
+  const mirror = path.join(ROOT, 'plugins/harness-everything/skills', relative);
+  check(fs.existsSync(mirror) && doc(relative) === fs.readFileSync(mirror, 'utf8'),
+    'Phase 2 OpenAI package mirror matches canonical: ' + relative);
+}
+
+console.log(`\n${failed === 0 ? 'PASS' : 'FAIL'}: #84 contract integrity phase 1-2 (${failed} failure${failed === 1 ? '' : 's'})`);
 process.exit(failed === 0 ? 0 : 1);