synergyspec-selfevolving 1.3.0 → 2.0.0

package/dist/core/self-evolution/health-baseline.js

@@ -17,10 +17,25 @@
  * first run records & allows), and writes are best-effort (a write failure must
  * never turn a successful promote into an error). Callers supply the timestamp,
  * so this module never calls Date.now (deterministic + replay-safe).
+ *
+ * Baselines are SCHEMA-VERSIONED ({@link HEALTH_METRICS_VERSION}): when the
+ * meaning/scale of `healthPenalty` changes (e.g. the move from the 7-metric
+ * blend to the SlopCodeBench structural_erosion⊕verbosity scores), reading a
+ * baseline stamped with a different version returns `null`, so an old-scale
+ * number can never mis-gate a new-scale measurement — the gate no-ops and the
+ * next promote re-seeds the baseline on the new scale.
  */
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 export const HEALTH_BASELINE_FILE = 'health-baseline.json';
+/**
+ * Schema version of the health-metrics scale behind `healthPenalty`. Bump
+ * whenever the meaning/scale of `healthPenalty` changes so stale baselines
+ * read as `null` instead of mis-gating. v2 = SlopCodeBench
+ * structural_erosion⊕verbosity; v1 (implicit/absent in old files) was the
+ * 7-metric blend.
+ */
+export const HEALTH_METRICS_VERSION = 2;
 function baselinePath(repoRoot) {
     return path.join(path.resolve(repoRoot), '.synergyspec-selfevolving', 'self-evolution', HEALTH_BASELINE_FILE);
 }
@@ -29,8 +44,10 @@ function isFiniteNumber(v) {
 }
 /**
  * Read the recorded baseline. Returns `null` when the file is absent, unreadable,
- * unparseable, or carries a non-finite `healthPenalty` (treated as "no baseline
- * yet" ⇒ the gate does not fire and the first measured run records it).
+ * unparseable, carries a non-finite `healthPenalty`, or was stamped with a
+ * `metricsVersion` other than {@link HEALTH_METRICS_VERSION} (an absent field ⇒
+ * a pre-versioning, old-scale baseline). All cases are treated as "no baseline
+ * yet" ⇒ the gate does not fire and the next promote re-seeds it.
  */
 export async function readHealthBaseline(repoRoot) {
     let raw;
@@ -52,23 +69,30 @@ export async function readHealthBaseline(repoRoot) {
     const obj = parsed;
     if (!isFiniteNumber(obj.healthPenalty))
         return null;
+    if (obj.metricsVersion !== HEALTH_METRICS_VERSION)
+        return null;
     return {
         healthPenalty: obj.healthPenalty,
         updatedAt: typeof obj.updatedAt === 'string' ? obj.updatedAt : '',
+        metricsVersion: obj.metricsVersion,
         ...(typeof obj.sourceChange === 'string' ? { sourceChange: obj.sourceChange } : {}),
         ...(typeof obj.candidateId === 'string' ? { candidateId: obj.candidateId } : {}),
     };
 }
 /**
- * Write/overwrite the recorded baseline. Best-effort: creates the parent dir if
- * needed and swallows any error (a failed baseline write must not fail a promote
- * that already succeeded). Returns `true` on a successful write, `false` otherwise.
+ * Write/overwrite the recorded baseline, stamping the current
+ * {@link HEALTH_METRICS_VERSION} (callers never supply it, so every written
+ * baseline is on the scale this build measures). Best-effort: creates the
+ * parent dir if needed and swallows any error (a failed baseline write must not
+ * fail a promote that already succeeded). Returns `true` on a successful write,
+ * `false` otherwise.
  */
 export async function writeHealthBaseline(repoRoot, baseline) {
     const file = baselinePath(repoRoot);
+    const stamped = { ...baseline, metricsVersion: HEALTH_METRICS_VERSION };
     try {
         await fs.mkdir(path.dirname(file), { recursive: true });
-        await fs.writeFile(file, `${JSON.stringify(baseline, null, 2)}\n`, 'utf8');
+        await fs.writeFile(file, `${JSON.stringify(stamped, null, 2)}\n`, 'utf8');
         return true;
     }
     catch {

package/dist/core/self-evolution/host-harness.d.ts

@@ -19,8 +19,7 @@
  * Back-compat is load-bearing: when the harness resolves to 'claude' (the
  * default - no CODEX_ or OPENCODE_ env present, as in the unit tests), the built
  * command is byte-identical to the previous behavior - `binary` + `['-p', prompt]`
- * with no stdin - so the existing proposer-agent / replay-runner tests pass
- * unchanged.
+ * with no stdin - so the existing headless-agent tests pass unchanged.
  */
 import { spawn as nodeSpawn } from 'node:child_process';
 export type AgentHarness = 'claude' | 'codex' | 'opencode';

package/dist/core/self-evolution/host-harness.js

@@ -19,8 +19,7 @@
  * Back-compat is load-bearing: when the harness resolves to 'claude' (the
  * default - no CODEX_ or OPENCODE_ env present, as in the unit tests), the built
  * command is byte-identical to the previous behavior - `binary` + `['-p', prompt]`
- * with no stdin - so the existing proposer-agent / replay-runner tests pass
- * unchanged.
+ * with no stdin - so the existing headless-agent tests pass unchanged.
  */
 import { spawn as nodeSpawn } from 'node:child_process';
 const HARNESSES = ['claude', 'codex', 'opencode'];

package/dist/core/self-evolution/index.d.ts

@@ -1,6 +1,5 @@
 export * from './shared.js';
 export * from './evolution-switches.js';
-export * from './template-variants.js';
 export * from './archive-memory.js';
 export * from './task-quality.js';
 export * from './alignment-verifier.js';
@@ -14,16 +13,21 @@ export * from './candidates.js';
 export * from './candidate-fitness.js';
 export * from './verdict.js';
 export * from './health-baseline.js';
-export * from './ga-selection.js';
-export * from './trajectory.js';
 export * from './host-harness.js';
-export * from './replay.js';
-export * from './replay-runner.js';
 export * from './credit-assignment.js';
 export * from './local-targets.js';
 export * from './promote.js';
 export * from './candidate-gates.js';
 export * from './eval-report.js';
-export * from './proposer-agent.js';
+export * from './edits-contract.js';
+export * from './proposer-slice.js';
 export * from './promotion.js';
+export * from './policy/index.js';
+export * from './episode-store.js';
+export * from './line-diff.js';
+export { checkScopeWithinDiagnosis, type ScopeViolation, type ScopeGateResult, type CheckScopeWithinDiagnosisInput, } from './scope-gate.js';
+export * from './critic-agent.js';
+export * from './reward-agent.js';
+export * from './evolving-agent.js';
+export * from './episode-orchestrator.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/self-evolution/index.js

@@ -1,6 +1,5 @@
 export * from './shared.js';
 export * from './evolution-switches.js';
-export * from './template-variants.js';
 export * from './archive-memory.js';
 export * from './task-quality.js';
 export * from './alignment-verifier.js';
@@ -14,16 +13,30 @@ export * from './candidates.js';
 export * from './candidate-fitness.js';
 export * from './verdict.js';
 export * from './health-baseline.js';
-export * from './ga-selection.js';
-export * from './trajectory.js';
 export * from './host-harness.js';
-export * from './replay.js';
-export * from './replay-runner.js';
 export * from './credit-assignment.js';
 export * from './local-targets.js';
 export * from './promote.js';
 export * from './candidate-gates.js';
 export * from './eval-report.js';
-export * from './proposer-agent.js';
+export * from './edits-contract.js';
+export * from './proposer-slice.js';
 export * from './promotion.js';
+// ── Loop v2 (self-evolution as in-context RL) ────────────────────────────────
+// Policy (ledger + reject-buffer + fs-safe), the disk episode store, the three
+// agents (critic / reward / evolving), the line-diff + scope gate, and the
+// rollback-before-evolution episode orchestrator. ArmObjective is the SINGLE
+// canonical on-disk type from critic-agent.js; reward-agent.js reads it via its
+// own null-safe RewardArmObjectiveInput, so this barrel has no ambiguous re-export.
+export * from './policy/index.js';
+export * from './episode-store.js';
+export * from './line-diff.js';
+// scope-gate.js also declares a DiagnosisGap ({file, section}); the richer
+// reward-agent.js DiagnosisGap ({file, section, description}) is the one the
+// barrel surfaces. Re-export the scope gate WITHOUT its DiagnosisGap.
+export { checkScopeWithinDiagnosis, } from './scope-gate.js';
+export * from './critic-agent.js';
+export * from './reward-agent.js';
+export * from './evolving-agent.js';
+export * from './episode-orchestrator.js';
 //# sourceMappingURL=index.js.map

package/dist/core/self-evolution/learn-hints.d.ts

@@ -12,6 +12,7 @@
  *     has no side effects, no dependencies, and never mutates inputs.
  */
 import type { CanonicalTargetKind } from './canonical-targets.js';
+import type { CreditPath } from '../learn/credit-path.js';
 /**
  * Closed enumeration of proposed change types a learn-stage hint may carry.
  *
@@ -58,6 +59,20 @@ export interface LearnEvolutionHintEvidence {
     quoteOrSummary: string;
     /** Severity of the observation in isolation. */
     severity: 'low' | 'medium' | 'high' | 'critical';
+    /**
+     * Where the evidence came from: `'observed'` = re-sourced from the observed
+     * runner output (the source the observed-verified gate trusts);
+     * `'authored'` = grepped from agent-authored artifacts. OPTIONAL — absent on
+     * legacy persisted hints (treated as authored).
+     */
+    provenance?: 'observed' | 'authored';
+    /**
+     * Rendered credit-path address from the failing signal back to the suspected
+     * producing canonical target, e.g. `test … → UC1-S2 → task 3.2 → design
+     * §"Normalizer" → artifact-template:design`. SUSPECT framing — recurrence
+     * across changes (the grouping machinery) is the confirmer. OPTIONAL.
+     */
+    address?: string;
 }
 /**
  * Structured hint emitted by `learn` for downstream candidate proposal.
@@ -100,6 +115,22 @@ export interface LearnEvolutionHint {
      * todo/learn-self-evolution-migration-plan.md.
      */
     loss?: number;
+    /**
+     * Full neutral credit paths (hops + bounded real-text excerpts) behind the
+     * evidence items' rendered `address` strings — the substrate the proposer
+     * slice is built from. Optional; absent on legacy persisted hints.
+     */
+    creditPaths?: CreditPath[];
+    /**
+     * `'policy-focus'` marks a hint SYNTHESIZED by the evolution-focus switch:
+     * every heuristic hint of this change bound to a frozen kind, so their
+     * evidence was re-aimed at an explicitly evolvable target instead of being
+     * silently dropped. SUSPECT framing — the hint asks the proposer to evaluate
+     * whether the focused target could prevent the signals' recurrence; it does
+     * NOT claim the focused target caused them. Optional; absent on ordinary
+     * heuristic hints and on legacy persisted hints.
+     */
+    origin?: 'policy-focus';
 }
 /**
  * Result of `validateLearnEvolutionHint`.

package/dist/core/self-evolution/learn-hints.js

@@ -76,6 +76,14 @@ function validateEvidenceItem(item, index, errors) {
     else if (!EVIDENCE_SEVERITY_SET.has(item.severity)) {
         errors.push(`${path}.severity must be one of low|medium|high|critical (got "${item.severity}")`);
     }
+    // Optional fields are validated ONLY when present, so legacy persisted hints
+    // (which predate them) keep validating unchanged.
+    if (item.provenance !== undefined && item.provenance !== 'observed' && item.provenance !== 'authored') {
+        errors.push(`${path}.provenance must be 'observed' or 'authored' when present`);
+    }
+    if (item.address !== undefined) {
+        pushNonEmptyStringError(errors, `${path}.address`, item.address);
+    }
 }
 /**
  * Runtime contract enforcer for `LearnEvolutionHint`.
@@ -144,6 +152,14 @@ export function validateLearnEvolutionHint(value) {
     if (value.loss !== undefined && (typeof value.loss !== 'number' || Number.isNaN(value.loss))) {
         errors.push('loss must be a number when present');
     }
+    // Optional, validated only when present (legacy persisted hints lack it).
+    if (value.creditPaths !== undefined && !Array.isArray(value.creditPaths)) {
+        errors.push('creditPaths must be an array when present');
+    }
+    // Optional, validated only when present (ordinary heuristic hints lack it).
+    if (value.origin !== undefined && value.origin !== 'policy-focus') {
+        errors.push(`origin must be 'policy-focus' when present (got "${String(value.origin)}")`);
+    }
     if (errors.length > 0) {
         return { ok: false, errors };
     }

package/dist/core/self-evolution/learn-observation-adapter.d.ts

@@ -1,5 +1,6 @@
 import { type LearnEvolutionHint } from './learn-hints.js';
 import { type TargetEvolutionPolicy } from './target-evolution.js';
+import { type CreditPath } from '../learn/credit-path.js';
 import { type LearnReport, type LearnObservation } from '../learn.js';
 /** The learn signals the interpreter reads (everything except the neutral observations). */
 type LearnSignals = Omit<LearnReport, 'observations'>;
@@ -24,6 +25,8 @@ type LearnSignals = Omit<LearnReport, 'observations'>;
  * should still wrap in try/catch and fall back to the registry source path.
  */
 export declare function resolveTargetLocalFilesReadonly(targetId: string, repoRoot: string): Promise<string[]>;
+/** Raw producing-target id for a path's last node (no policy annotation). */
+export declare function producingTargetIdForCreditPath(creditPath: CreditPath): string | undefined;
 /**
  * Derive structured evolution hints from a learn report's signals.
  *
@@ -47,6 +50,20 @@ export declare function generateEvolutionHints(report: LearnSignals, policy?: Ta
  * hint entirely (no evolvable target of its kind exists).
  */
 export declare function resolveKindOnlyPinTarget(draft: LearnEvolutionHint, policy: TargetEvolutionPolicy): string | undefined | null;
+/**
+ * The evolution-focus target ids: the explicitly evolvable, REGISTERED
+ * canonical targets of a frozen-by-default policy, with the focus switch ON.
+ *
+ * Empty (focus inactive) when:
+ * - the switch is off (`selfEvolution.focus: false` / `learn --no-focus`),
+ * - the policy default is `evolvable` (nothing is dropped as frozen-kind in the
+ *   way focus rescues — and "evolve everything" needs no focus), or
+ * - no explicit target survives (freeze-wins already resolved into `explicit`).
+ *
+ * Exported for the learn command's transparency rendering, so the printed focus
+ * line cannot drift from the hint-synthesis pass.
+ */
+export declare function resolveEvolutionFocusTargets(policy: TargetEvolutionPolicy | undefined): string[];
 /**
  * Surface an AMBIGUOUS kind-only evolution hint as an action-required
  * observation. After {@link scopeHintsByPolicy} runs, a hint that still has no
@@ -63,12 +80,30 @@ export declare function resolveKindOnlyPinTarget(draft: LearnEvolutionHint, poli
  * unbindable, keeping learn output byte-identical in the common case.
  */
 export declare function detectUnbindableHintObservations(hints: LearnEvolutionHint[], policy: TargetEvolutionPolicy | undefined): LearnObservation[];
+/**
+ * Surface health offenders whose routing lands on a FROZEN target as ONE
+ * aggregated ACTION-REQUIRED observation — the honest dead-end. Without this,
+ * a freezing policy makes the offender signal vanish silently: the enrichment
+ * in {@link generateEvolutionHints} only rides on drafts that survive scoping.
+ * Mirrors {@link detectUnbindableHintObservations}' shape and wiring (call it
+ * wherever that one is called, on evolving runs). Returns `[]` when `policy`
+ * is absent or the routing target is evolvable — the enrichment path already
+ * carries the signal there — so the common case stays byte-identical.
+ */
+export declare function detectFrozenHealthRoutingObservations(report: LearnSignals, policy?: TargetEvolutionPolicy): LearnObservation[];
 /**
  * Persist hints to the canonical handoff path that `propose-canonical
  * --from-learn` reads (`{ evolutionHints: [...] }`). This is the one-motion
  * learn → propose bridge: it writes an ARTIFACT under `learn-handoffs/` (never a
  * canonical file), so it is proposal-only. Reuses the existing
  * `learn-handoffs/<change>/<timestamp>/` convention. Returns the file path.
+ *
+ * When any hint carries credit paths, a sibling `slice.md` is written next to
+ * `hints.json` (and referenced via the optional top-level `slice` key) so the
+ * HOST author on the `--from-edits` path can read the real artifact text along
+ * the failing paths — the same CREDIT-PATH SLICE the `--agent` prompt renders.
+ * Old readers ignore unknown top-level keys (`extractHintCandidates` reads only
+ * the hint arrays), so the addition is back-compatible.
  */
 export declare function persistLearnHints(opts: {
     projectRoot: string;