synergyspec-selfevolving 1.3.0 → 1.4.0

package/README.md

@@ -211,10 +211,28 @@ What actually works today:
   `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
+  scores Python, Rust, C, and C++ by computing the SlopCodeBench
+  `structural_erosion` and `verbosity` scores (for Python, the slop rules are
+  the actual SlopCodeBench v0.3 ast-grep rule set, bundled) — 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).
+- **Rollout/critic separation** (`learn` → `synergyspec-selfevolving-self-evolving`):
+  the end-of-cycle critique runs in a fresh-context critic subagent — an
+  always-installed utility skill that reads only the on-disk record
+  (transcripts, hints, evolution result, learn report) and returns a
+  `## Critic Verdict` block that the thin `learn` relays. The session that did
+  the work never grades its own rollout; hosts without subagents run the critic
+  inline, marked as degraded isolation. Headless and fresh-context invokers can
+  pass explicit trajectory handles (`--transcript` / `--session-id` on `learn`,
+  `learn handoff`, `learn debug-trajectory`, and `evolve-from-edits`, or the
+  `SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT` / `SYNERGYSPEC_SELFEVOLVING_SESSION_ID`
+  env vars; flags beat env vars, transcript beats session-id). An explicit
+  handle beats change-window discovery and never silently grades another
+  session: an unresolvable flag is an up-front error (exit non-zero), while a
+  missing env handle fails closed — no trajectory, and the observed-verified
+  gate refuses to promote.
 - **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

package/dist/commands/learn.js

@@ -1,12 +1,14 @@
 import path from 'node:path';
 import { applyLearnCandidates, applyLearnMemoryCandidates, generateLearnReport, renderLearnReport, } from '../core/learn.js';
-import { detectUnbindableHintObservations, generateEvolutionHints, isCanonicalTargetEvolvable, listCanonicalTargets, lookupCanonicalTarget, persistLearnHints, resolveTargetEvolutionPolicy, resolveTargetLocalFilesReadonly, } from '../core/self-evolution/index.js';
+import { detectFrozenHealthRoutingObservations, 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';
+import { findTranscriptsForChange, resolveChangeDir, validateExplicitTrajectoryHandle, } from '../core/learn/trajectory-discovery.js';
 import { getTrajectoryForChange } from '../core/trajectory/registry.js';
 import { toTrajectoryFacts, describeRunnerResults } from '../core/trajectory/facts.js';
+import { toActionSkeleton } from '../core/trajectory/skeleton.js';
 import { resolveHostHarness } from '../core/self-evolution/host-harness.js';
+import { mineSuccessSignals } from '../core/self-evolution/success-channel.js';
 import { buildLLMSummaryCandidates, ingestLearnHandoff, } from '../core/learn/llm-summary.js';
 function collect(value, previous) {
     previous.push(value);
@@ -21,15 +23,62 @@ export function registerLearnCommand(program) {
         .option('--only <candidate-id>', 'When applying, write only this keep candidate id (repeatable)', collect, [])
         .option('--exclude <candidate-id>', 'When applying, skip this candidate id (repeatable)', collect, [])
         .option('-y, --yes', 'Confirm --apply and skip confirmation prompts')
-        .option('--persist-hints', 'Persist derived evolution hints to a learn-handoffs/ file for propose-canonical --from-learn (proposal-only; implied by --apply)')
+        .option('--persist-hints', 'Persist derived evolution hints to a learn-handoffs/ file consumed by self-evolution evolve-from-edits --from-learn (writes no canonical file; implied by --apply)')
         .option('--evolve-target <ids>', 'comma-separated canonical target ids whose hints learn may emit (supports all/none); overrides config selfEvolution for this run')
         .option('--freeze-target <ids>', 'comma-separated canonical target ids whose hints learn must NOT emit (supports all/none; beats --evolve-target)')
+        .option('--no-focus', 'Disable the evolution-focus switch for this run: when the policy is frozen-by-default, frozen-kind signals are dropped silently instead of being re-aimed at the explicitly evolvable target(s) as a policy-focus hint (config: selfEvolution.focus)')
+        .option('--transcript <path>', 'Explicit transcript .jsonl to grade (bypasses change-window discovery; Claude transcript store only)')
+        .option('--session-id <id>', 'Explicit Claude session id to grade (bypasses change-window discovery; Claude transcript store only)')
         .option('--json', 'Output as JSON')
         .option('--no-interactive', 'Disable interactive prompts (learn is non-interactive by default)')
         .action(async (change, options) => {
         try {
             const projectRoot = process.cwd();
-            const report = await generateLearnReport({ projectRoot, changeName: change });
+            // USER-TYPED handle flags are validated up front and fail LOUD
+            // (exit 1) on a miss — unlike the env-var channel, which keeps the
+            // fail-closed refusal semantics inside discovery (empty result, the
+            // gate refuses), and unlike debug-trajectory, which is the diagnostic
+            // that SHOWS the miss. Validated BEFORE the env is mutated below so a
+            // bad flag never leaks into the environment.
+            const handleError = await validateExplicitTrajectoryHandle({
+                projectRoot,
+                transcriptPath: options.transcript,
+                sessionId: options.sessionId,
+            });
+            if (handleError)
+                throw new Error(handleError);
+            // Explicit trajectory handle: surfaced to the discovery layer via env
+            // (same set/restore shape as debug-trajectory's --harness) so it
+            // reaches the registry adapter inside generateLearnReport without
+            // changing any core signature. Restored as soon as the report exists.
+            const prevTranscriptEnv = process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT;
+            const prevSessionEnv = process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID;
+            if (options.transcript)
+                process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT = options.transcript;
+            if (options.sessionId)
+                process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID = options.sessionId;
+            let report;
+            try {
+                report = await generateLearnReport({ projectRoot, changeName: change });
+            }
+            finally {
+                if (options.transcript) {
+                    if (prevTranscriptEnv === undefined) {
+                        delete process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT;
+                    }
+                    else {
+                        process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT = prevTranscriptEnv;
+                    }
+                }
+                if (options.sessionId) {
+                    if (prevSessionEnv === undefined) {
+                        delete process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID;
+                    }
+                    else {
+                        process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID = prevSessionEnv;
+                    }
+                }
+            }
             if (options.apply === true && options.yes !== true) {
                 throw new Error('learn --apply requires --yes to confirm memory writes');
             }
@@ -40,6 +89,7 @@ export function registerLearnCommand(program) {
                 config: readProjectConfig(projectRoot),
                 evolveTarget: options.evolveTarget,
                 freezeTarget: options.freezeTarget,
+                focus: options.focus,
             });
             const evolutionHints = generateEvolutionHints(report, targetPolicy);
             const evolutionPreview = await buildEvolutionPreview(evolutionHints, targetPolicy, projectRoot);
@@ -49,10 +99,11 @@ export function registerLearnCommand(program) {
             // 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));
+            if (isEvolvingRun(options)) {
+                report.observations.push(...detectUnbindableHintObservations(evolutionHints, targetPolicy), 
+                // Health offenders whose producing target is frozen are a routing
+                // dead-end the operator must see (ACTION), never a silent drop.
+                ...detectFrozenHealthRoutingObservations(report, targetPolicy));
             }
             const applied = options.apply === true
                 ? await applyLearnCandidates({
@@ -77,6 +128,7 @@ export function registerLearnCommand(program) {
                     config: readProjectConfig(projectRoot),
                     evolveTarget: options.evolveTarget,
                     freezeTarget: options.freezeTarget,
+                    focus: options.focus,
                 });
                 const hints = generateEvolutionHints(report, targetPolicy);
                 if (hints.length > 0) {
@@ -87,6 +139,24 @@ export function registerLearnCommand(program) {
                     });
                 }
             }
+            // SUCCESS CHANNEL (R4): on an opt-in evolving run (--apply /
+            // --persist-hints) a verified-GREEN report mines load-bearing
+            // protections + exemplars — side-writes only, never a candidate, so
+            // abstain-on-success is untouched. A bare preview `learn` run never
+            // reaches this (no files created), and the mining is best-effort so a
+            // side-write failure never fails the learn run.
+            let successSummary;
+            if (options.apply === true || options.persistHints === true) {
+                try {
+                    const mined = await mineSuccessSignals({ projectRoot, report });
+                    if (mined.protectionsWritten > 0) {
+                        successSummary = `Success channel: recorded ${mined.protectionsWritten} protection(s) for ${mined.protectedTargets.join(', ')}`;
+                    }
+                }
+                catch {
+                    // side-write only; never fail learn over it.
+                }
+            }
             if (options.json) {
                 printJson(report, applied, evolutionPreview, hintsPath);
                 return;
@@ -94,6 +164,10 @@ export function registerLearnCommand(program) {
             console.log(renderLearnReport(report, applied));
             console.log('');
             console.log(renderLearnTransparency(report, applied, evolutionPreview, hintsPath, options));
+            if (successSummary) {
+                console.log('');
+                console.log(successSummary);
+            }
         }
         catch (error) {
             if (options.json) {
@@ -110,10 +184,20 @@ export function registerLearnCommand(program) {
         .description('Print the assembled TrajectoryContext for a change as JSON. Read-only; runs no LLM handoff and writes nothing.')
         .option('--preview', 'Truncate the trajectory text field to 4000 chars in the output')
         .option('--harness <name>', 'Force the observed-run trajectory adapter (claude|codex|opencode); defaults to the resolved host harness')
-        .action(async (change, opts) => {
+        .option('--transcript <path>', 'Explicit transcript .jsonl to grade (bypasses change-window discovery; Claude transcript store only)')
+        .option('--session-id <id>', 'Explicit Claude session id to grade (bypasses change-window discovery; Claude transcript store only)')
+        .action(async (change, _opts, command) => {
         const projectRoot = process.cwd();
+        // --transcript/--session-id are also declared on the parent `learn`
+        // command, which consumes them before this subcommand sees them.
+        // optsWithGlobals() merges ancestor + local options so the explicit
+        // handle is honored either way.
+        const opts = command.optsWithGlobals();
         try {
-            const discovered = await findTranscriptsForChange(change, projectRoot);
+            const discovered = await findTranscriptsForChange(change, projectRoot, {
+                transcriptPath: opts.transcript,
+                sessionId: opts.sessionId,
+            });
             const assembled = await assembleTrajectoryContext({
                 changeName: change,
                 projectRoot,
@@ -137,8 +221,17 @@ export function registerLearnCommand(program) {
             // its facts + per-runner-result breakdown so a misgrade is visible in one
             // command. `--harness` forces a specific adapter for cross-host debugging.
             const prevHarnessEnv = process.env.SYNERGYSPEC_SELFEVOLVING_HOST_HARNESS;
+            const prevTranscriptEnv = process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT;
+            const prevSessionEnv = process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID;
             if (opts.harness)
                 process.env.SYNERGYSPEC_SELFEVOLVING_HOST_HARNESS = opts.harness;
+            // The explicit trajectory handle must reach the adapter's own discovery
+            // call too (env is the only channel through the registry), so the
+            // introspected payload reflects the same override as `discovery` above.
+            if (opts.transcript)
+                process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT = opts.transcript;
+            if (opts.sessionId)
+                process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID = opts.sessionId;
             try {
                 const adapterTrajectory = await getTrajectoryForChange(projectRoot, change);
                 payload.adapter = {
@@ -148,6 +241,9 @@ export function registerLearnCommand(program) {
                     sourcePaths: adapterTrajectory ? [...new Set(adapterTrajectory.sourcePaths)] : [],
                     facts: toTrajectoryFacts(adapterTrajectory, change),
                     runnerResults: describeRunnerResults(adapterTrajectory),
+                    // Bounded play-by-play projection (file edits / test runs /
+                    // commands) so a wrong skeleton is visible in one command.
+                    steps: toActionSkeleton(adapterTrajectory),
                 };
             }
             finally {
@@ -159,6 +255,22 @@ export function registerLearnCommand(program) {
                         process.env.SYNERGYSPEC_SELFEVOLVING_HOST_HARNESS = prevHarnessEnv;
                     }
                 }
+                if (opts.transcript) {
+                    if (prevTranscriptEnv === undefined) {
+                        delete process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT;
+                    }
+                    else {
+                        process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT = prevTranscriptEnv;
+                    }
+                }
+                if (opts.sessionId) {
+                    if (prevSessionEnv === undefined) {
+                        delete process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID;
+                    }
+                    else {
+                        process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID = prevSessionEnv;
+                    }
+                }
             }
             if (assembled.kind === 'ok') {
                 const t = assembled.trajectory;
@@ -194,25 +306,69 @@ export function registerLearnCommand(program) {
     learnCmd
         .command('handoff <change>')
         .description('Write an LLM trajectory-extraction brief for a change and return immediately (no polling). Fulfill it in-session by writing memory-items.md, then run `learn ingest-handoff`.')
+        .option('--transcript <path>', 'Explicit transcript .jsonl to grade (bypasses change-window discovery; Claude transcript store only)')
+        .option('--session-id <id>', 'Explicit Claude session id to grade (bypasses change-window discovery; Claude transcript store only)')
         .option('--json', 'Output as JSON')
         .action(async (change, _opts, command) => {
         const projectRoot = process.cwd();
-        // The parent `learn [change]` command also declares --json, so it
-        // consumes the flag before the subcommand sees it. optsWithGlobals()
-        // merges ancestor + local options so the flag is honored either way.
+        // The parent `learn [change]` command also declares --json, --transcript
+        // and --session-id, so it consumes the flags before the subcommand sees
+        // them. optsWithGlobals() merges ancestor + local options so they are
+        // honored either way.
         const opts = command.optsWithGlobals();
         try {
-            const changeDir = await resolveChangeDir(projectRoot, change);
-            // forceEnable: invoking this command IS the opt-in, so it does not
-            // depend on SYNERGYSPEC_SELFEVOLVING_LEARN_LLM. pollForResponse:false
-            // is what avoids the single-actor poll deadlock.
-            const result = await buildLLMSummaryCandidates({
+            // USER-TYPED handle flags fail LOUD up front (exit 1) — without this
+            // a bad --session-id would silently fall back to window discovery,
+            // the exact failure mode the explicit handles exist to kill.
+            const handleError = await validateExplicitTrajectoryHandle({
                 projectRoot,
-                changeName: change,
-                changeDir,
-                pollForResponse: false,
-                forceEnable: true,
+                transcriptPath: opts.transcript,
+                sessionId: opts.sessionId,
             });
+            if (handleError)
+                throw new Error(handleError);
+            const changeDir = await resolveChangeDir(projectRoot, change);
+            // The explicit trajectory handle must reach the discovery call inside
+            // buildLLMSummaryCandidates (env is the only channel through it), so
+            // set/restore the same way the main learn action does. Restored as
+            // soon as the trajectory assembly returns.
+            const prevTranscriptEnv = process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT;
+            const prevSessionEnv = process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID;
+            if (opts.transcript)
+                process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT = opts.transcript;
+            if (opts.sessionId)
+                process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID = opts.sessionId;
+            let result;
+            try {
+                // forceEnable: invoking this command IS the opt-in, so it does not
+                // depend on SYNERGYSPEC_SELFEVOLVING_LEARN_LLM. pollForResponse:false
+                // is what avoids the single-actor poll deadlock.
+                result = await buildLLMSummaryCandidates({
+                    projectRoot,
+                    changeName: change,
+                    changeDir,
+                    pollForResponse: false,
+                    forceEnable: true,
+                });
+            }
+            finally {
+                if (opts.transcript) {
+                    if (prevTranscriptEnv === undefined) {
+                        delete process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT;
+                    }
+                    else {
+                        process.env.SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT = prevTranscriptEnv;
+                    }
+                }
+                if (opts.sessionId) {
+                    if (prevSessionEnv === undefined) {
+                        delete process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID;
+                    }
+                    else {
+                        process.env.SYNERGYSPEC_SELFEVOLVING_SESSION_ID = prevSessionEnv;
+                    }
+                }
+            }
             if (!result) {
                 throw new Error('handoff stage returned no result');
             }
@@ -458,6 +614,11 @@ async function buildEvolutionPreview(hints, targetPolicy, projectRoot) {
             target.localFiles = [];
         }
     }
+    // Surface the evolution-focus re-aim explicitly: a synthesized
+    // `origin: 'policy-focus'` hint means every ordinary signal of this change
+    // bound to a frozen kind and its evidence was re-aimed at the focused
+    // target(s). Agents read this field instead of inferring from hint ids.
+    const focusHints = hints.filter((hint) => hint.origin === 'policy-focus');
     return {
         hintCount: hints.length,
         targetPolicy: {
@@ -468,6 +629,16 @@ async function buildEvolutionPreview(hints, targetPolicy, projectRoot) {
             ...(targetPolicy.source.cliEvolve ? { cliEvolve: targetPolicy.source.cliEvolve } : {}),
             ...(targetPolicy.source.cliFreeze ? { cliFreeze: targetPolicy.source.cliFreeze } : {}),
         },
+        ...(focusHints.length > 0
+            ? {
+                focus: {
+                    targetIds: [
+                        ...new Set(focusHints.flatMap((hint) => hint.affectedTargetId ? [hint.affectedTargetId] : [])),
+                    ].sort((left, right) => left.localeCompare(right)),
+                    hintIds: focusHints.map((hint) => hint.id),
+                },
+            }
+            : {}),
         targets: [...byTarget.values()].sort((left, right) => (left.targetId ?? `~${left.targetKind}`).localeCompare(right.targetId ?? `~${right.targetKind}`)),
     };
 }
@@ -507,9 +678,15 @@ function renderLearnTransparency(report, applied, evolutionPreview, hintsPath, o
     lines.push('');
     lines.push('### Skill/Template Optimization Preview');
     lines.push(`- Evolution policy: default=${evolutionPreview.targetPolicy.default}${renderExplicitPolicy(evolutionPreview.targetPolicy.explicit)}`);
+    if (evolutionPreview.focus) {
+        lines.push(`- Evolution focus: ${evolutionPreview.focus.targetIds.join(', ')} — every signal of this change bound to a frozen kind, so the dropped evidence was re-aimed at the focused target as ${evolutionPreview.focus.hintIds.join(', ')} (origin: policy-focus). Disable with --no-focus or selfEvolution.focus: false.`);
+    }
     if (evolutionPreview.targets.length === 0) {
         lines.push('- Target: none under the current evidence and evolve/freeze policy.');
         lines.push('- How: no prompt/template/skill optimization will be proposed from this learn report unless more evidence is added or the target policy is widened.');
+        if (options.focus === false && evolutionPreview.targetPolicy.default === 'frozen') {
+            lines.push('- Note: the evolution-focus switch is disabled for this run (--no-focus); frozen-kind signals, if any, were dropped without a focus re-aim.');
+        }
     }
     else {
         for (const target of evolutionPreview.targets) {
@@ -566,12 +743,37 @@ function renderLearnTransparency(report, applied, evolutionPreview, hintsPath, o
     else if (evolutionPreview.targets.length > 0) {
         lines.push(`- Persist the optimization evidence: synergyspec-selfevolving learn "${report.changeName}" --persist-hints${renderTargetArgs(options)}`);
     }
-    lines.push('');
-    lines.push('headless fallback (no host agent):');
-    lines.push(`- One-button local evolve: synergyspec-selfevolving self-evolution auto-evolve --change "${report.changeName}" --agent${renderTargetArgs(options)}`);
-    lines.push('- After reviewing or evolving, run /synspec:archive to close the change.');
+    else if (isEvolvingRun(options)) {
+        // Empty-target evolving run: say so explicitly instead of leaving the
+        // section blank and falling through to the headless fallback (ses_148b:
+        // that fallthrough made the skill-banned `--agent` steering the only
+        // actionable next-step a host agent saw).
+        lines.push('- No evolvable optimization target bound under the current evidence and evolve/freeze policy — a safe no-op (Outcome: not-run).');
+    }
+    if (isEvolvingRun(options)) {
+        lines.push('- After reviewing or evolving, run /synspec:archive to close the change.');
+    }
+    else {
+        lines.push('');
+        lines.push('headless fallback (no host agent):');
+        lines.push(`- One-button local evolve: synergyspec-selfevolving self-evolution auto-evolve --change "${report.changeName}"${renderTargetArgs(options)}`);
+        lines.push('- After reviewing or evolving, run /synspec:archive to close the change.');
+    }
     return lines.join('\n');
 }
+/**
+ * An "evolving run" is one where the operator opted into evolution
+ * (`--apply` / `--persist-hints` / a named `--evolve-target`) — per the skill,
+ * the bare CLI previews and only the skill/agent flow passes these flags, so
+ * this is the agent-in-the-loop proxy (the same signal that gates the
+ * unbindable-hint observations in the learn action). The headless
+ * `auto-evolve` fallback (it spawns its proposer internally) is for runs with
+ * NO agent in the loop; the skill forbids the headless proposer when an agent
+ * IS the proposer, so the fallback is suppressed on evolving runs.
+ */
+function isEvolvingRun(options) {
+    return (options.apply === true || options.persistHints === true || options.evolveTarget !== undefined);
+}
 function renderExplicitPolicy(explicit) {
     if (explicit.length === 0)
         return '';