synergyspec-selfevolving 1.1.10 → 1.1.12

package/README.md

@@ -208,9 +208,18 @@ What actually works today:
 - **Per-change fitness loss** (`learn`): `loss = 0.7·(1 − pass_rate) +
   0.3·health_penalty`, in `[0,1]`. The functional term comes from the change's
   gen-test/run-test pass rate; the code-health term is fed by a swappable
-  `MetricSource` selected via `health:` in `synergyspec-selfevolving/config.yaml`
-  (`stub` → no health signal by default; `local-python` → `scripts/code-health.py`;
-  `sonarqube`). With no `health` config the loss is functional-only.
+  `MetricSource` selected via `health:` in `synergyspec-selfevolving/config.yaml`.
+  New projects scaffold `source: local` (default-on): a dependency-free,
+  multi-language analyzer (`scripts/code-health.py`, Python 3 stdlib only) that
+  scores Python, Rust, C, and C++ — no server, no network. Set `source: stub` to
+  make the loss functional-only; `sonarqube` is also supported; `local-python` is
+  a back-compat alias for `local`. See
+  [docs/customization.md](docs/customization.md#code-health-metrics-self-evolution).
+- **Code-health gate** (auto-evolve / `evolve-from-edits`): a measured code-health
+  regression vs the last accepted state blocks auto-promotion (and surfaces a
+  loud `health-signal-unavailable` observation if a configured analyzer can't
+  run). No health signal ⇒ no gate, so the loop is never blocked on a missing
+  measurement.
 - **Candidate proposals** (`self-evolution propose-canonical`): turns aggregated
   `learn` hints into human-gated candidate packages under
   `.synergyspec-selfevolving/self-evolution/candidates/`. Proposal-only — no

package/dist/commands/learn.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { applyLearnCandidates, applyLearnMemoryCandidates, generateLearnReport, renderLearnReport, } from '../core/learn.js';
-import { generateEvolutionHints, lookupCanonicalTarget, persistLearnHints, resolveTargetEvolutionPolicy, resolveTargetLocalFilesReadonly, } from '../core/self-evolution/index.js';
+import { detectUnbindableHintObservations, generateEvolutionHints, isCanonicalTargetEvolvable, listCanonicalTargets, lookupCanonicalTarget, persistLearnHints, resolveTargetEvolutionPolicy, resolveTargetLocalFilesReadonly, } from '../core/self-evolution/index.js';
 import { readProjectConfig } from '../core/project-config.js';
 import { assembleTrajectoryContext, } from '../core/learn/trajectory-assembler.js';
 import { findTranscriptsForChange, resolveChangeDir, } from '../core/learn/trajectory-discovery.js';
@@ -43,6 +43,17 @@ export function registerLearnCommand(program) {
             });
             const evolutionHints = generateEvolutionHints(report, targetPolicy);
             const evolutionPreview = await buildEvolutionPreview(evolutionHints, targetPolicy, projectRoot);
+            // Surface an unbindable kind-only hint (one that could not pin to a concrete
+            // target) as an actionable DEFECT observation, so a failed target binding is
+            // not silently rationalized as a safe gate refusal — but ONLY when the operator
+            // is actually trying to evolve (--apply / --persist-hints / a named
+            // --evolve-target). On a plain preview run the kind-only ambiguity is the
+            // designed state, not a defect, so a bare `learn <change>` stays byte-identical.
+            if (options.apply === true ||
+                options.persistHints === true ||
+                options.evolveTarget !== undefined) {
+                report.observations.push(...detectUnbindableHintObservations(evolutionHints, targetPolicy));
+            }
             const applied = options.apply === true
                 ? await applyLearnCandidates({
                     projectRoot,
@@ -349,22 +360,61 @@ function renderIngestHandoff(changeName, ingest, applied) {
     return lines.join('\n');
 }
 function printJson(report, applied, evolutionPreview, hintsPath) {
+    // `mode` only tracks whether MEMORY candidates were applied (--apply). It does
+    // NOT reflect that --persist-hints wrote a hints file, which is what made the
+    // old `mode:"preview"` read as "nothing written". `wrote` makes every write this
+    // run produced explicit.
+    const wrote = [];
+    if (hintsPath)
+        wrote.push(hintsPath);
+    if (applied) {
+        for (const item of applied.written)
+            wrote.push(`memory:${item.memoryId}`);
+    }
+    // Flat "how many hints, and is each ready to evolve or does it need a pin?" view
+    // so the agent never has to infer readiness from the richer evolutionPreview.
+    const evolution = {
+        hintsGenerated: evolutionPreview.hintCount,
+        targets: evolutionPreview.targets.map((target) => ({
+            targetId: target.targetId,
+            targetKind: target.targetKind,
+            pinned: target.targetId !== null,
+            unbindable: target.needsDisambiguation,
+            candidateTargetIds: target.candidateTargetIds,
+            hintIds: target.hintIds,
+        })),
+    };
     console.log(JSON.stringify({
         mode: applied ? 'apply' : 'preview',
         ...report,
         applied,
         evolutionPreview,
         ...(hintsPath ? { hintsPath } : {}),
+        wrote,
+        evolution,
     }, null, 2));
 }
 async function buildEvolutionPreview(hints, targetPolicy, projectRoot) {
     const byTarget = new Map();
     for (const hint of hints) {
-        const targetId = hint.affectedTargetId ?? `${hint.affectedTargetKind}:unspecified`;
-        const target = hint.affectedTargetId ? lookupCanonicalTarget(hint.affectedTargetId) : undefined;
-        const current = byTarget.get(targetId) ?? {
-            targetId,
+        const pinned = hint.affectedTargetId ?? null;
+        // Group key only — an unpinned kind-only hint groups under an internal
+        // `__unbindable__:<kind>` key that is NEVER emitted (the emitted `targetId`
+        // stays null), so the `<kind>:unspecified` placeholder no longer leaks out.
+        const groupKey = pinned ?? `__unbindable__:${hint.affectedTargetKind}`;
+        const target = pinned ? lookupCanonicalTarget(pinned) : undefined;
+        const current = byTarget.get(groupKey) ?? {
+            targetId: pinned,
             targetKind: hint.affectedTargetKind,
+            needsDisambiguation: pinned === null,
+            // Only offer same-kind ids that are actually EVOLVABLE under the policy, so the
+            // operator is never told to `--evolve-target` a frozen id (which would then be
+            // refused). Matches detectUnbindableHintObservations' candidate list exactly.
+            candidateTargetIds: pinned === null
+                ? listCanonicalTargets({ kind: hint.affectedTargetKind })
+                    .filter((candidate) => isCanonicalTargetEvolvable(candidate.id, targetPolicy))
+                    .map((candidate) => candidate.id)
+                : [],
             files: target?.files ? [...target.files] : [],
             localFiles: [],
             hintIds: [],
@@ -391,7 +441,7 @@ async function buildEvolutionPreview(hints, targetPolicy, projectRoot) {
                 });
             }
         }
-        byTarget.set(targetId, current);
+        byTarget.set(groupKey, current);
     }
     // Resolve each concrete target to its LOCAL file path(s) in THIS repo,
     // best-effort and READ-ONLY (never materialize during a plain preview). A
@@ -399,7 +449,7 @@ async function buildEvolutionPreview(hints, targetPolicy, projectRoot) {
     // empty and the renderer falls back to the registry source path. On any throw
     // we leave localFiles empty and fall back as well.
     for (const target of byTarget.values()) {
-        if (!lookupCanonicalTarget(target.targetId))
+        if (target.targetId === null)
             continue;
         try {
             target.localFiles = await resolveTargetLocalFilesReadonly(target.targetId, projectRoot);
@@ -418,7 +468,7 @@ async function buildEvolutionPreview(hints, targetPolicy, projectRoot) {
             ...(targetPolicy.source.cliEvolve ? { cliEvolve: targetPolicy.source.cliEvolve } : {}),
             ...(targetPolicy.source.cliFreeze ? { cliFreeze: targetPolicy.source.cliFreeze } : {}),
         },
-        targets: [...byTarget.values()].sort((left, right) => left.targetId.localeCompare(right.targetId)),
+        targets: [...byTarget.values()].sort((left, right) => (left.targetId ?? `~${left.targetKind}`).localeCompare(right.targetId ?? `~${right.targetKind}`)),
     };
 }
 function renderLearnTransparency(report, applied, evolutionPreview, hintsPath, options) {
@@ -463,7 +513,9 @@ function renderLearnTransparency(report, applied, evolutionPreview, hintsPath, o
     }
     else {
         for (const target of evolutionPreview.targets) {
-            lines.push(`- Target: ${target.targetId} (${target.targetKind})`);
+            lines.push(target.targetId === null
+                ? `- Target: (${target.targetKind}, unpinned — needs --evolve-target)`
+                : `- Target: ${target.targetId} (${target.targetKind})`);
             // Prefer the CONCRETE local file the writer would edit; fall back to the
             // registry source path. Only a genuinely kind-only/ambiguous group with no
             // resolvable file shows the 'not pinned' notice.
@@ -484,7 +536,7 @@ function renderLearnTransparency(report, applied, evolutionPreview, hintsPath, o
     // A "concrete" target is one pinned to a registered canonical id (not a
     // kind-only `<kind>:unspecified` group). The host agent authors edits.json's
     // full new content for that target's resolved LOCAL file.
-    const concreteTargets = evolutionPreview.targets.filter((target) => lookupCanonicalTarget(target.targetId));
+    const concreteTargets = evolutionPreview.targets.filter((target) => target.targetId !== null);
     const concreteTarget = concreteTargets.length > 0 ? concreteTargets[0] : undefined;
     if (hintsPath && concreteTarget) {
         lines.push(`- Hints written: ${hintsPath}`);
@@ -494,7 +546,22 @@ function renderLearnTransparency(report, applied, evolutionPreview, hintsPath, o
     }
     else if (hintsPath) {
         lines.push(`- Hints written: ${hintsPath}`);
-        lines.push('- No single concrete target resolved yet; add evidence or widen the target policy so a specific file can be pinned for evolve-from-edits.');
+        // A kind-only (`<kind>:unspecified`) hint can't be promoted by
+        // evolve-from-edits until it is pinned to ONE concrete target. The remedy is
+        // to NAME a single target via --evolve-target — NOT to "widen the policy"
+        // (widening keeps several same-kind targets evolvable, so the hint stays
+        // unpinned). List the registered candidates so the operator can pick one.
+        const candidates = [
+            ...new Set(evolutionPreview.targets
+                .filter((target) => target.targetId === null)
+                .flatMap((target) => target.candidateTargetIds)),
+        ];
+        if (candidates.length > 0) {
+            lines.push(`- No single concrete target resolved yet. Pin one by re-running with --evolve-target <id> (candidates: ${candidates.join(', ')}); then evolve-from-edits can consume the hint.`);
+        }
+        else {
+            lines.push('- No single concrete target resolved yet; add evidence so a specific file can be pinned for evolve-from-edits.');
+        }
     }
     else if (evolutionPreview.targets.length > 0) {
         lines.push(`- Persist the optimization evidence: synergyspec-selfevolving learn "${report.changeName}" --persist-hints${renderTargetArgs(options)}`);

package/dist/commands/self-evolution.d.ts

@@ -179,6 +179,8 @@ export interface AutoEvolveReport {
     changeNames: string[];
     /** Mean per-change loss (functional ⊕ health) from learn; null when unmeasurable. */
     loss: number | null;
+    /** Mean RAW code-health penalty across the change(s); null when no health signal. */
+    healthPenalty?: number | null;
     hintCount: number;
     hintsPaths: string[];
     proposed: string[];
@@ -237,8 +239,19 @@ export interface RunEvolveFromEditsOptions {
      */
     generateReport?: (changeName: string) => Promise<LearnReport>;
 }
+/**
+ * Typed, machine-readable result of an evolve-from-edits run. Refusals (the
+ * `refused-*` values) are LEGITIMATE non-promotions and keep `exitCode: 0` so the
+ * autonomous learn skill treats them as "safe, move on"; only the `error-*` values
+ * are non-zero. This is additive to the human-facing `reason`/`error` strings — it
+ * lets callers (and `status`) tell "did it promote, and if not, was that a safe
+ * refusal or a defect?" without parsing prose.
+ */
+export type EvolveFromEditsOutcome = 'promoted' | 'refused-no-surviving-hint' | 'refused-static-gate' | 'refused-unverified-evidence' | 'refused-auto-promote-declined' | 'refused-health-regression' | 'error-unknown-target' | 'error-bad-input' | 'error-runtime';
 export interface EvolveFromEditsReport {
     exitCode: number;
+    /** Typed result. `refused-*` ⇒ exitCode 0 (safe); `error-*` ⇒ non-zero. */
+    outcome: EvolveFromEditsOutcome;
     targetId: string;
     /** The host candidate that was packaged (the gate/promote subject). */
     candidateId: string | null;

package/dist/commands/self-evolution.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import fastGlob from 'fast-glob';
-import { aggregateLearnEvolutionHints, applyCandidatePromotion, rollbackCandidatePromotion, shouldAutoPromote, isEvidenceComplete, generateEvolutionHints, persistLearnHints, readCandidateFitness, readCandidatePackage, resolveTargetLocalFiles, CANONICAL_CANDIDATE_SOURCES, CANONICAL_TARGETS, collectArchiveExperiences, EVOLVABLE_PART_DESCRIPTIONS, EVOLVABLE_PARTS, evaluateTaskDecompositionForChange, evaluateToolEvolutionCandidate, generateCandidateId, generatePromotionReport, groupCandidatesByTarget, rankCandidatesForTarget, makeReplayRunChange, scoreCandidatesByReplay, isEvolutionPartEnabled, findSimilarArchiveExperiences, listCanonicalTargets, lookupCanonicalTarget, runCanonicalProposerAgent, validateCandidateEdits, renderUnifiedDiff, CanonicalProposerNoOp, resolveTargetEvolutionPolicy, isCanonicalTargetEvolvable, parseEvolutionSwitchOptions, readTemplateVariantManifest, renderAlignmentReport, renderArchiveExperienceBlock, renderStaticGateSummary, renderToolEvolutionGuardReport, renderEvolutionSwitches, requireCanonicalTarget, resolveCandidateRepo, runStaticCandidateGate, selectTemplateVariant, shouldTriggerCandidate, validateLearnEvolutionHint, writeCandidatePackage, verifySpecCodeAlignmentForChange, } from '../core/self-evolution/index.js';
+import { aggregateLearnEvolutionHints, applyCandidatePromotion, rollbackCandidatePromotion, shouldAutoPromote, isEvidenceComplete, generateEvolutionHints, persistLearnHints, readCandidateFitness, readHealthBaseline, writeHealthBaseline, readCandidatePackage, resolveTargetLocalFiles, CANONICAL_CANDIDATE_SOURCES, CANONICAL_TARGETS, collectArchiveExperiences, EVOLVABLE_PART_DESCRIPTIONS, EVOLVABLE_PARTS, evaluateTaskDecompositionForChange, evaluateToolEvolutionCandidate, generateCandidateId, generatePromotionReport, groupCandidatesByTarget, rankCandidatesForTarget, makeReplayRunChange, scoreCandidatesByReplay, isEvolutionPartEnabled, findSimilarArchiveExperiences, listCanonicalTargets, lookupCanonicalTarget, runCanonicalProposerAgent, validateCandidateEdits, renderUnifiedDiff, CanonicalProposerNoOp, resolveTargetEvolutionPolicy, isCanonicalTargetEvolvable, parseEvolutionSwitchOptions, readTemplateVariantManifest, renderAlignmentReport, renderArchiveExperienceBlock, renderStaticGateSummary, renderToolEvolutionGuardReport, renderEvolutionSwitches, requireCanonicalTarget, resolveCandidateRepo, runStaticCandidateGate, selectTemplateVariant, shouldTriggerCandidate, validateLearnEvolutionHint, writeCandidatePackage, verifySpecCodeAlignmentForChange, } from '../core/self-evolution/index.js';
 import { generateLearnReport } from '../core/learn.js';
 import { resolveMetricSource } from '../core/fitness/index.js';
 import { validateChangeExists, validateSchemaExists } from './workflow/shared.js';
@@ -957,6 +957,7 @@ export async function runAutoEvolve(args, opts) {
     // and several aggregate a recurring signal across them. Each change's hints are
     // persisted; a failed change is skipped, not fatal.
     const losses = [];
+    const healthSignals = [];
     const hintsPaths = [];
     let totalHints = 0;
     for (const changeName of args.changeNames) {
@@ -974,6 +975,9 @@ export async function runAutoEvolve(args, opts) {
         const l = learnReport.fitnessSample?.loss?.loss;
         if (typeof l === 'number')
             losses.push(l);
+        const h = learnReport.fitnessSample?.healthSignal;
+        if (typeof h === 'number')
+            healthSignals.push(h);
         const hints = generateEvolutionHints(learnReport, policy);
         totalHints += hints.length;
         if (hints.length === 0)
@@ -981,6 +985,13 @@ export async function runAutoEvolve(args, opts) {
         hintsPaths.push(await persistLearnHints({ projectRoot: opts.repoRoot, changeName, hints, now }));
     }
     report.loss = losses.length > 0 ? losses.reduce((a, b) => a + b, 0) / losses.length : null;
+    // Mean RAW health signal across the change(s); null when none were measured
+    // (stub source / no signal) ⇒ the health gate below cannot fire.
+    const meanHealth = healthSignals.length > 0
+        ? healthSignals.reduce((a, b) => a + b, 0) / healthSignals.length
+        : null;
+    report.healthPenalty = meanHealth;
+    const healthBaseline = await readHealthBaseline(opts.repoRoot);
     report.hintCount = totalHints;
     report.hintsPaths = hintsPaths;
     if (hintsPaths.length === 0) {
@@ -1067,6 +1078,8 @@ export async function runAutoEvolve(args, opts) {
             meanLoss: fitness.meanLoss,
             baselineLoss: report.loss,
             requireProvenImprovement: args.requireProven === true,
+            healthPenalty: meanHealth,
+            baselineHealthPenalty: healthBaseline?.healthPenalty ?? null,
         });
         if (!autoPromote) {
             report.skipped.push({
@@ -1097,6 +1110,16 @@ export async function runAutoEvolve(args, opts) {
             });
         }
     }
+    // Record the accepted health as the new per-repo baseline (best-effort) when
+    // this run promoted something and had a real health signal. The next run's
+    // health gate compares against this value.
+    if (report.promoted.length > 0 && meanHealth != null) {
+        await writeHealthBaseline(opts.repoRoot, {
+            healthPenalty: meanHealth,
+            updatedAt: now().toISOString(),
+            sourceChange: args.changeNames.join(','),
+        });
+    }
     finishAutoEvolve(report, args.json, stdout, stderr);
     return report;
 }
@@ -1156,6 +1179,9 @@ export async function runEvolveFromEdits(args, opts) {
         ((changeName) => generateLearnReport({ projectRoot: opts.repoRoot, changeName }));
     const report = {
         exitCode: 0,
+        // Loud fallback: a terminal path that forgets to set its outcome surfaces as
+        // an error rather than a silent (and wrong) success.
+        outcome: 'error-runtime',
         targetId: args.evolveTarget,
         candidateId: null,
         gatePassed: false,
@@ -1163,9 +1189,21 @@ export async function runEvolveFromEdits(args, opts) {
         promotedFiles: [],
         loss: null,
     };
-    const fail = (code, message) => {
+    // The change this run pertains to (derived from the hints path), used to write
+    // the machine-readable evolution-result.json that `status` surfaces.
+    const changeName = changeNameFromHints(args.fromLearn);
+    const persist = () => persistEvolutionResult(opts.repoRoot, changeName, report, now);
+    const fail = (code, outcome, message, 
+    // Pure CLI-misuse refusals (bad flags / unregistered target) do NOT write a
+    // per-change evolution-result.json — they are not a defect of the change, and
+    // a fat-fingered flag should not leave a durable `error-*` record that `status`
+    // surfaces. Only paths that actually attempted the evolution persist a record.
+    persistRecord = true) => {
         report.exitCode = code;
+        report.outcome = outcome;
         report.error = message;
+        if (persistRecord)
+            persist();
         if (args.json) {
             stdout(JSON.stringify(report, null, 2));
         }
@@ -1177,10 +1215,25 @@ export async function runEvolveFromEdits(args, opts) {
     // Non-interactive contract: --yes is required (mirrors auto-evolve's one-button
     // confirmation), and --agent is REFUSED (this path is host-authored, never spawns).
     if (args.agent) {
-        return fail(2, '--agent is not allowed: evolve-from-edits is host-authored and never spawns the proposer.');
+        return fail(2, 'error-bad-input', '--agent is not allowed: evolve-from-edits is host-authored and never spawns the proposer.', false);
     }
     if (!args.yes) {
-        return fail(2, '--yes is required: evolve-from-edits promotes onto your local files non-interactively.');
+        return fail(2, 'error-bad-input', '--yes is required: evolve-from-edits promotes onto your local files non-interactively.', false);
+    }
+    // Reject an unregistered / kind-only sentinel target EARLY (before propose) with a
+    // helpful list of concrete same-kind ids. An unpinned kind-only hint surfaces as
+    // `<kind>:unspecified`, which is NOT a registered canonical target; feeding it back
+    // here would otherwise fail late with a bare "Unknown canonical target". Exit code 1
+    // matches the prior behavior (requireCanonicalTarget threw inside propose → exit 1).
+    if (!lookupCanonicalTarget(args.evolveTarget)) {
+        const kind = args.evolveTarget.includes(':') ? args.evolveTarget.split(':')[0] : '';
+        const candidates = kind
+            ? listCanonicalTargets({ kind: kind }).map((t) => t.id)
+            : [];
+        const hint = candidates.length > 0
+            ? ` Concrete ${kind} targets you can pin: ${candidates.join(', ')}.`
+            : ' Run `self-evolution targets` to list registered ids.';
+        return fail(1, 'error-unknown-target', `--evolve-target "${args.evolveTarget}" is not a registered canonical target.${hint}`, false);
     }
     // 1) Read + shape-validate the host-authored edits (path or stdin).
     let editsInput;
@@ -1191,7 +1244,7 @@ export async function runEvolveFromEdits(args, opts) {
         editsInput = parseHostEditsInput(raw);
     }
     catch (err) {
-        return fail(2, `invalid --from-edits ${args.fromEdits}: ${err instanceof Error ? err.message : String(err)}`);
+        return fail(2, 'error-bad-input', `invalid --from-edits ${args.fromEdits}: ${err instanceof Error ? err.message : String(err)}`, false);
     }
     const layout = resolveCandidateRepo(opts.repoRoot);
     const policy = resolveTargetEvolutionPolicy({
@@ -1226,7 +1279,14 @@ export async function runEvolveFromEdits(args, opts) {
         });
     }
     catch (err) {
-        return fail(1, `propose failed: ${err instanceof Error ? err.message : String(err)}`);
+        const message = err instanceof Error ? err.message : String(err);
+        // After the early --evolve-target check above this is mostly unreachable for
+        // unknown targets, but keep the discrimination as defense in depth. Exit code 1
+        // for both (matches the prior propose-catch behavior).
+        const outcome = message.startsWith('Unknown canonical target')
+            ? 'error-unknown-target'
+            : 'error-runtime';
+        return fail(1, outcome, `propose failed: ${message}`);
     }
     if (proposeResult.exitCode !== 0 || proposeResult.proposed.length === 0) {
         // A frozen target / unknown target / >1 group / no surviving group lands here.
@@ -1235,7 +1295,11 @@ export async function runEvolveFromEdits(args, opts) {
             proposeResult.skipped.map((s) => s.reason)[0] ??
             'no candidate was packaged from the host edits (target frozen, unknown, or no surviving signal)';
         report.reason = why;
-        finishEvolveFromEdits(report, args.json, stdout, stderr);
+        // Legitimate refusal: exitCode stays 0 so the autonomous learn skill treats it
+        // as "safe, move on" — do NOT propagate proposeResult.exitCode (2 for the
+        // surviving-group guard).
+        report.outcome = 'refused-no-surviving-hint';
+        finishEvolveFromEdits(report, args.json, stdout, stderr, persist);
         return report;
     }
     const candidateId = proposeResult.proposed[0].candidateId;
@@ -1249,7 +1313,7 @@ export async function runEvolveFromEdits(args, opts) {
         });
     }
     catch (err) {
-        return fail(1, `gate error: ${err instanceof Error ? err.message : String(err)}`);
+        return fail(1, 'error-runtime', `gate error: ${err instanceof Error ? err.message : String(err)}`);
     }
     report.gatePassed = gate.passed;
     if (!gate.passed) {
@@ -1257,7 +1321,8 @@ export async function runEvolveFromEdits(args, opts) {
             .filter((f) => f.severity === 'error')
             .map((f) => f.message)
             .join('; ') || 'placeholder/no-op diff or frozen target'}`;
-        finishEvolveFromEdits(report, args.json, stdout, stderr);
+        report.outcome = 'refused-static-gate';
+        finishEvolveFromEdits(report, args.json, stdout, stderr, persist);
         return report;
     }
     // 4) OBSERVED-VERIFIED evidence + auto-promote decision. Regenerate the change's
@@ -1268,16 +1333,22 @@ export async function runEvolveFromEdits(args, opts) {
         learnReport = await generateReport(changeNameFromHints(args.fromLearn));
     }
     catch (err) {
-        return fail(1, `learn report failed: ${err instanceof Error ? err.message : String(err)}`);
+        return fail(1, 'error-runtime', `learn report failed: ${err instanceof Error ? err.message : String(err)}`);
     }
     report.loss = learnReport.fitnessSample?.loss?.loss ?? null;
     const evidence = isEvidenceComplete(learnReport);
     if (!evidence.ok) {
         report.reason = `evidence not observed-verified-green: ${evidence.reason}`;
-        finishEvolveFromEdits(report, args.json, stdout, stderr);
+        report.outcome = 'refused-unverified-evidence';
+        finishEvolveFromEdits(report, args.json, stdout, stderr, persist);
         return report;
     }
     const fitness = await readCandidateFitness(layout, candidateId);
+    // Default-on health gate: compare THIS change's measured health (post) against
+    // the recorded per-repo baseline (pre). No signal (stub/analyzer failed) ⇒
+    // healthSignal is null ⇒ the gate cannot fire (forward bet preserved).
+    const healthSignal = learnReport.fitnessSample?.healthSignal ?? null;
+    const baseline = await readHealthBaseline(opts.repoRoot);
     const decision = shouldAutoPromote({
         gatePassed: true,
         targetEvolvable: isCanonicalTargetEvolvable(args.evolveTarget, policy),
@@ -1285,10 +1356,15 @@ export async function runEvolveFromEdits(args, opts) {
         meanLoss: fitness.meanLoss,
         baselineLoss: report.loss,
         requireProvenImprovement: args.requireProven === true,
+        healthPenalty: healthSignal,
+        baselineHealthPenalty: baseline?.healthPenalty ?? null,
     });
     if (!decision.promote) {
         report.reason = `auto-promote declined: ${decision.reason}`;
-        finishEvolveFromEdits(report, args.json, stdout, stderr);
+        report.outcome = decision.reason.startsWith('code-health regression')
+            ? 'refused-health-regression'
+            : 'refused-auto-promote-declined';
+        finishEvolveFromEdits(report, args.json, stdout, stderr, persist);
         return report;
     }
     // 5) PROMOTE onto the canonical LOCAL file(s).
@@ -1301,25 +1377,85 @@ export async function runEvolveFromEdits(args, opts) {
         report.promotedFiles = applied.appliedFiles.map((f) => f.file);
     }
     catch (err) {
-        return fail(1, `promote failed: ${err instanceof Error ? err.message : String(err)}`);
+        return fail(1, 'error-runtime', `promote failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Record the accepted health as the new baseline (best-effort; never fails the
+    // promote) — only when this run had a real health signal. The next change's
+    // gate compares against this value.
+    if (healthSignal != null) {
+        await writeHealthBaseline(opts.repoRoot, {
+            healthPenalty: healthSignal,
+            updatedAt: now().toISOString(),
+            sourceChange: changeNameFromHints(args.fromLearn),
+            candidateId,
+        });
     }
-    finishEvolveFromEdits(report, args.json, stdout, stderr);
+    report.outcome = 'promoted';
+    finishEvolveFromEdits(report, args.json, stdout, stderr, persist);
     return report;
 }
 /**
- * Best-effort change-name for the learn report when one is needed. The hints
- * file path's parent dir is the handoff dir (`<...>/<change>/hints.json`); fall
- * back to the file basename. learn re-resolves the active change anyway, so this
- * only steers `generateLearnReport` toward the right change directory.
+ * Best-effort change-name for the hints path passed to `--from-learn`.
+ *
+ * `persistLearnHints` writes the canonical handoff at
+ * `<root>/.synergyspec-selfevolving/learn-handoffs/<change>/<timestamp>/hints.json`,
+ * so on the REAL autonomous path the change name is the GRANDPARENT of hints.json
+ * (the immediate parent is the timestamp). We detect that shape via the
+ * `learn-handoffs` marker and return the grandparent; otherwise we fall back to the
+ * immediate parent dir (the 2-level shape used by tests / hand-built paths), then
+ * the file basename. This is the name used for BOTH the learn report and the
+ * evolution-result.json write, so they cannot diverge.
  */
 function changeNameFromHints(hintsPath) {
     const abs = path.resolve(hintsPath);
-    const parent = path.basename(path.dirname(abs));
+    const workdir = path.dirname(abs);
+    const parent = path.basename(workdir);
+    const grandparent = path.basename(path.dirname(workdir));
+    // Canonical: learn-handoffs/<change>/<timestamp>/hints.json → change = grandparent.
+    if (path.basename(path.dirname(path.dirname(workdir))) === 'learn-handoffs' && grandparent) {
+        return grandparent;
+    }
     if (parent && parent !== '.' && parent !== path.sep)
         return parent;
     return path.basename(abs, path.extname(abs));
 }
-function finishEvolveFromEdits(report, json, stdout, stderr) {
+/**
+ * Write a machine-readable evolution outcome beside the change's other evidence
+ * (`synergyspec-selfevolving/changes/<change>/evolution-result.json`) so `status`
+ * can surface whether self-evolution promoted, was safely refused, or hit a defect
+ * — instead of the outcome only living in the agent-written learn-report.md.
+ *
+ * Best-effort: it NEVER throws (a write failure must not turn a successful promote
+ * into an error) and it does NOT create the change dir — if the change dir is absent
+ * (a typo'd/invalid invocation, or an already-archived change) it simply skips.
+ */
+function persistEvolutionResult(repoRoot, changeName, report, now) {
+    try {
+        const changeDir = path.join(repoRoot, 'synergyspec-selfevolving', 'changes', changeName);
+        if (!fs.existsSync(changeDir))
+            return;
+        const record = {
+            schemaVersion: 1,
+            changeName,
+            outcome: report.outcome,
+            promoted: report.promoted,
+            reason: report.reason ?? report.error ?? null,
+            targetId: report.targetId,
+            candidateId: report.candidateId,
+            gatePassed: report.gatePassed,
+            promotedFiles: report.promotedFiles,
+            loss: report.loss,
+            timestamp: now().toISOString(),
+            tool: 'evolve-from-edits',
+        };
+        fs.writeFileSync(path.join(changeDir, 'evolution-result.json'), `${JSON.stringify(record, null, 2)}\n`);
+    }
+    catch {
+        // best-effort: a status-annotation write must never break the evolve run.
+    }
+}
+function finishEvolveFromEdits(report, json, stdout, stderr, persist) {
+    persist?.();
     if (json) {
         stdout(JSON.stringify(report, null, 2));
         return;

package/dist/commands/workflow/status.js

@@ -57,6 +57,19 @@ export function printStatusText(status, readiness) {
         else {
             console.log(chalk.green('Evidence: complete'));
         }
+        // Self-evolution outcome (visibility only; never gates archive-ready). A
+        // refused/failed evolution is surfaced in YELLOW so a silently-failed evolution
+        // can't hide inside an otherwise-green, archive-ready run.
+        const evolution = readiness.evolution;
+        if (evolution.status === 'promoted' && evolution.promoted) {
+            console.log(chalk.green(`Evolution: promoted -> ${evolution.targetId ?? '(target)'} (${evolution.promotedFiles.length} file(s))`));
+        }
+        else if (evolution.status === 'refused' || evolution.status === 'error' || evolution.status === 'promoted') {
+            console.log(chalk.yellow(`Evolution: ${evolution.status}${evolution.reason ? ` — ${evolution.reason}` : ''}`));
+        }
+        else {
+            console.log(chalk.dim('Evolution: not run'));
+        }
     }
     console.log();
     for (const artifact of status.artifacts) {

package/dist/core/change-readiness.d.ts

@@ -2,6 +2,13 @@ import { type ChangeStatus } from './artifact-graph/index.js';
 export type ArtifactWorkflowStatus = 'complete' | 'ready' | 'in-progress' | 'blocked';
 export type ChangeReadinessStatus = ArtifactWorkflowStatus | 'ready-to-apply';
 export type TaskReadinessStatus = 'no-tasks' | 'complete' | 'in-progress';
+/**
+ * Coarse, display-oriented self-evolution outcome for the change. Derived from the
+ * CLI-written `evolution-result.json` (NOT the agent-written learn-report.md). It is
+ * surfaced for visibility only — it does NOT gate `isArchiveReady` (a safe refusal
+ * must not block archiving a finished change).
+ */
+export type EvolutionOutcomeStatus = 'not-run' | 'promoted' | 'refused' | 'error';
 export interface ArtifactStatusSummary {
     done: number;
     ready: number;
@@ -26,6 +33,20 @@ export interface EvidenceReadiness {
     testPlanRequired: boolean;
     missing: string[];
 }
+export interface EvolutionOutcomeReadiness {
+    /** `'not-run'` when no `evolution-result.json` exists for the change. */
+    status: EvolutionOutcomeStatus;
+    /** Why it stopped (refusal reason or error message); absent when promoted/not-run. */
+    reason?: string;
+    /** The canonical target the run was for (when known). */
+    targetId?: string;
+    /** Whether a canonical file was actually promoted. */
+    promoted: boolean;
+    /** LOCAL file paths written on promotion (empty unless promoted). */
+    promotedFiles: string[];
+    /** ISO timestamp of the recorded run. */
+    timestamp?: string;
+}
 export interface ChangeReadiness {
     changeName: string;
     schemaName: string;
@@ -37,6 +58,8 @@ export interface ChangeReadiness {
     totalTasks: number;
     incompleteTasks: TaskItem[];
     evidence: EvidenceReadiness;
+    /** Self-evolution outcome for the change (visibility only; does not gate archive). */
+    evolution: EvolutionOutcomeReadiness;
     isArchiveReady: boolean;
     artifactGraph: ChangeStatus;
 }
@@ -54,6 +77,7 @@ export declare function toReadinessJson(readiness: ChangeReadiness): {
     totalTasks: number;
     incompleteTasks: TaskItem[];
     evidence: EvidenceReadiness;
+    evolution: EvolutionOutcomeReadiness;
     isArchiveReady: boolean;
 };
 //# sourceMappingURL=change-readiness.d.ts.map