@hmharness/evolution 0.18.15 → 0.19.1

package/dist/cognitive-audit.d.ts

@@ -0,0 +1,55 @@
+export interface EvolutionOutcomeLike {
+    name: string;
+    action: 'promoted' | 'rejected' | 'error';
+    reason: string;
+    baseline?: {
+        passRate: number;
+    };
+    candidate?: {
+        passRate: number;
+    };
+    holdout?: {
+        baselineRate: number;
+        candidateRate: number;
+    };
+    lineage?: {
+        parentInsights?: string[];
+        scores?: Record<string, number | undefined>;
+        metaModel?: string;
+        decidedAt?: string;
+    };
+}
+export interface SkillContract {
+    hypothesis: string;
+    expected: string;
+    regression: string;
+}
+/** Parse the blueprint declaration header from a skill draft's markdown. */
+export declare function parseSkillContract(skillMd: string): SkillContract | null;
+export interface AuditEvent {
+    at: string;
+    event: 'promoted' | 'rejected' | 'error' | 'rolled-back' | 'contract-rejected';
+    candidateId: string;
+    target: string;
+    hypothesis: string;
+    detail: Record<string, unknown>;
+}
+/** Append one outcome to the immutable audit trail (best-effort, never throws). */
+export declare function auditEvolutionOutcome(home: string, outcome: EvolutionOutcomeLike, skillMd?: string): Promise<void>;
+/** EV-012 at the canary/impact seam: bench pass-rate is the METRIC; real
+ *  sessions' impact delta is the TASK. Metric up + task flat = Goodhart. */
+export declare function checkCanaryRewardHacking(input: {
+    benchPassRateBefore: number;
+    benchPassRateAfter: number;
+    realTaskSuccessBefore: number;
+    realTaskSuccessAfter: number;
+}): {
+    hacked: boolean;
+    reason?: string;
+};
+/** Strict mode gate (evolution.requireContract=true): undeclared drafts are
+ *  rejected BEFORE bench spend, with an audit trail entry saying why. */
+export declare function enforceContractGate(home: string, name: string, skillMd: string, requireContract: boolean): Promise<{
+    pass: boolean;
+    contract: SkillContract | null;
+}>;

package/dist/cognitive-audit.js

@@ -0,0 +1,84 @@
+/**
+ * @hmharness/evolution - cognitive audit bridge (blueprint EV-002/EV-011/EV-012)
+ *
+ * Every evolve-loop outcome lands in the IMMUTABLE cognitive audit trail
+ * (HMH_HOME/cognitive/evolution/audit.jsonl) with the blueprint's candidate
+ * contract when the draft declares one:
+ *
+ *   Hypothesis: <what changes and why it should work>
+ *   Expected: <metric op value>
+ *   Regression: <what this could hurt>
+ *
+ * Drafts WITHOUT declarations still audit (declared:false) — visible
+ * honesty, not silent acceptance. Teams can enforce the blueprint strictly
+ * with evolution.requireContract=true in config: undeclared candidates are
+ * then rejected before any bench spend.
+ */
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { detectRewardHacking } from '@hmharness/cognitive';
+/** Parse the blueprint declaration header from a skill draft's markdown. */
+export function parseSkillContract(skillMd) {
+    const grab = (key) => {
+        const m = skillMd.match(new RegExp(`^\\s*${key}\\s*[:：]\\s*(.+)$`, 'mi'));
+        return m?.[1]?.trim() ?? '';
+    };
+    const hypothesis = grab('Hypothesis');
+    const expected = grab('Expected');
+    const regression = grab('Regression');
+    if (!hypothesis || !regression)
+        return null;
+    return { hypothesis, expected: expected || 'unspecified', regression };
+}
+/** Append one outcome to the immutable audit trail (best-effort, never throws). */
+export async function auditEvolutionOutcome(home, outcome, skillMd) {
+    try {
+        const contract = skillMd ? parseSkillContract(skillMd) : null;
+        const event = {
+            at: outcome.lineage?.decidedAt ?? new Date().toISOString(),
+            event: outcome.action === 'promoted' ? 'promoted' : outcome.action === 'rejected' ? /rolled back/i.test(outcome.reason) ? 'rolled-back' : 'rejected' : 'error',
+            candidateId: outcome.name,
+            target: 'skill',
+            hypothesis: contract?.hypothesis ?? '(undeclared draft — no Hypothesis/Regression header)',
+            detail: {
+                reason: outcome.reason,
+                declared: Boolean(contract),
+                contract,
+                trainBaseline: outcome.baseline?.passRate,
+                trainCandidate: outcome.candidate?.passRate,
+                holdoutBaseline: outcome.holdout?.baselineRate,
+                holdoutCandidate: outcome.holdout?.candidateRate,
+                lineage: outcome.lineage,
+            },
+        };
+        const dir = join(home, 'cognitive', 'evolution');
+        await mkdir(dir, { recursive: true });
+        await appendFile(join(dir, 'audit.jsonl'), JSON.stringify(event) + '\n', 'utf8');
+    }
+    catch {
+        /* audit is best-effort by contract */
+    }
+}
+/** EV-012 at the canary/impact seam: bench pass-rate is the METRIC; real
+ *  sessions' impact delta is the TASK. Metric up + task flat = Goodhart. */
+export function checkCanaryRewardHacking(input) {
+    return detectRewardHacking({
+        metricBefore: input.benchPassRateBefore,
+        metricAfter: input.benchPassRateAfter,
+        realTaskSuccessBefore: input.realTaskSuccessBefore,
+        realTaskSuccessAfter: input.realTaskSuccessAfter,
+    });
+}
+/** Strict mode gate (evolution.requireContract=true): undeclared drafts are
+ *  rejected BEFORE bench spend, with an audit trail entry saying why. */
+export async function enforceContractGate(home, name, skillMd, requireContract) {
+    const contract = parseSkillContract(skillMd);
+    if (contract || !requireContract)
+        return { pass: true, contract };
+    await auditEvolutionOutcome(home, {
+        name,
+        action: 'rejected',
+        reason: 'evolution.requireContract=true and the draft has no Hypothesis/Regression declaration (blueprint EV-002 contract gate)',
+    }, skillMd);
+    return { pass: false, contract: null };
+}

package/dist/evolve.js

@@ -196,9 +196,22 @@ export async function runEvolution(opts) {
     }
     catch { /* default floor */ }
     // 5. A/B gate each proposal on the train set.
+    const draftsMd = new Map();
     for (const p of proposals.slice(0, maxProposals)) {
+        draftsMd.set(p.name, p.skill_md);
         say(`candidate "${p.name}": drafting + candidate bench`);
         try {
+            // Cognitive OS contract gate (blueprint EV-002, strict mode only):
+            // with evolution.requireContract=true a draft must DECLARE hypothesis
+            // + possible regression before any bench budget is spent on it.
+            const { enforceContractGate } = await import("./cognitive-audit.js");
+            const requireContract = Boolean(opts.requireContract);
+            const contractGate = await enforceContractGate(home, p.name, p.skill_md, requireContract);
+            if (!contractGate.pass) {
+                report.outcomes.push({ name: p.name, action: 'rejected', reason: 'contract gate: draft lacks Hypothesis/Regression declaration (evolution.requireContract)' });
+                say('  rejected by contract gate (no declaration)');
+                continue;
+            }
             // Write-channel anti-poisoning (Misevolve lesson): the behavior gate
             // only sees bench output, so instructions the model merely IGNORES
             // slip through. Screen drafted content for attempts to suppress tool
@@ -361,6 +374,16 @@ export async function runEvolution(opts) {
             say(`  error: ${String(err).slice(0, 120)}`);
         }
     }
+    // Cognitive OS immutable audit (blueprint EV-011): every outcome of this
+    // cycle lands in cognitive/evolution/audit.jsonl — promoted, rejected,
+    // rolled-back or error, declared contract or honest declared:false.
+    {
+        const { auditEvolutionOutcome } = await import("./cognitive-audit.js");
+        for (const o of report.outcomes) {
+            const draftMd = draftsMd.get(o.name);
+            await auditEvolutionOutcome(home, o, draftMd);
+        }
+    }
     // 6. CODE-LEVEL evolution: propose + sandbox-bench + merge/revert patches.
     // This is the DGM bridge - the agent can now modify its own tool code,
     // gated by the same bench discipline as skill promotion.

package/dist/index.d.ts

@@ -24,3 +24,4 @@ export * from './context-evolution.js';
 export * from './rl-governance.js';
 export * from './policy-optimizer.js';
 export * from './cloud-finetune.js';
+export * from './cognitive-audit.js';

package/dist/index.js

@@ -24,3 +24,4 @@ export * from "./context-evolution.js";
 export * from "./rl-governance.js";
 export * from "./policy-optimizer.js";
 export * from "./cloud-finetune.js";
+export * from "./cognitive-audit.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/evolution",
-  "version": "0.18.15",
+  "version": "0.19.1",
   "description": "hmharness evolution subsystem: persistent memory, insight capture, skill library, and the bench that gives evolution its fitness signal. First-class kernel citizen, not a plugin.",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,8 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@hmharness/kernel": "0.18.15"
+    "@hmharness/cognitive": "0.19.1",
+    "@hmharness/kernel": "0.19.1"
   },
   "files": [
     "dist"