synergyspec-selfevolving 1.3.0 → 2.0.0

package/README.md

@@ -133,7 +133,7 @@ Now tell your AI: `/synspec:propose <what-you-want-to-build>`
 → **[Workflows](docs/workflows.md)**: combos and patterns<br>
 → **[Commands](docs/commands.md)**: slash commands & skills<br>
 → **[CLI](docs/cli.md)**: terminal reference<br>
-→ **[Evaluation Lab](docs/evaluation-lab.md)**: advanced self-evolution harness<br>
+→ **[Self-Evolution Loop](docs/evaluation-lab.md)**: the loop-v2 in-context RL surface<br>
 → **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths<br>
 → **[Concepts](docs/concepts.md)**: how it all fits<br>
 → **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
@@ -199,9 +199,9 @@ The self-evolution machinery lives in-tree under `src/core/fitness` and
 `src/core/self-evolution`, exposed through the `synergyspec-selfevolving
 self-evolution` subcommands (not as an ordinary day-to-day skill). It treats the
 spec workflow as a learnable system — a change is a forward pass through the
-artifact templates; `learn` runs the backward pass (a per-change loss); and a
-genetic-algorithm outer loop selects among competing candidate template
-variants.
+artifact templates; `learn` runs the backward pass (a per-change loss); and an
+in-context-RL episode improves one design 策略 POLICY lineage from a graded
+advantage, with a rollback that fires *before* any new edit.
 
 What actually works today:
 
@@ -211,25 +211,53 @@ 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).
-- **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
+- **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** (the episode's evolving agent / `evolve-from-edits`): a
+  measured code-health regression vs the last accepted state blocks 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
   canonical file is modified, and the frozen gen-test/run-test oracle is never
   touched.
-- **GA outer loop** (`self-evolution evolve`): groups candidates by canonical
-  target, scores them by accumulated fitness (or `--replay <corpus>` to re-run a
-  change corpus through baseline vs. candidate), ranks them, and generates a
-  **human-gated** promotion report. It never auto-promotes, and a frozen target
-  (per the per-target evolution policy) is skipped.
+- **In-context-RL episode** (`self-evolution episode --change <name>`): runs ONE
+  completed change through a fixed, code-spawned pipeline. A two-arm forward grades
+  the **主智能体 MAIN AGENT** (the frozen current 策略 POLICY) from the change's
+  `learn` report against a **CRITIC AGENT（基线智能体 baseline agent）** that reruns
+  the prior policy on the same change; a **奖励智能体 REWARD AGENT** computes
+  **advantage ＝ reward(主臂) − reward(基线臂)** and names the gap; on a bad advantage
+  the orchestrator rolls the 策略 POLICY back *before* the **演进智能体 EVOLVING
+  AGENT** is called; the evolving agent then makes ONE bounded edit (or refuses)
+  after the static / observed-GREEN / 范围⊆诊断 gates pass, writing the next policy
+  version onto your LOCAL files — no candidate dir, no republish. A frozen target
+  (per the per-target evolution policy) is skipped. Inspect the lineage with
+  `self-evolution policy show [--target <id>]`, re-enter a partial run with
+  `self-evolution episode resume <id>`, and manually restore a version with
+  `self-evolution policy rollback --target <id> --yes`. See
+  [docs/evaluation-lab.md](docs/evaluation-lab.md).
 - **Per-target evolution scope** (`selfEvolution:` in
   `synergyspec-selfevolving/config.yaml`): one switch decides which canonical
   targets may evolve, honored end-to-end by `learn` → `propose-canonical` → the
@@ -242,13 +270,16 @@ What actually works today:
 
 What is **not** built yet (don't infer it from the architecture diagrams):
 
-- No autonomous multi-generation **breeding** loop (mutate winners → next
-  generation). `evolve` runs a single generation over pre-existing candidates;
-  new candidates only come from the human-gated `propose-canonical` step.
+- No autonomous multi-episode **breeding** loop. Each `self-evolution episode`
+  improves the policy from one change's graded advantage; it never fans out
+  competing variants or runs unattended generations. New manual candidates only
+  come from the human-gated `propose-canonical` step.
 - No measured benchmark gains. The mechanisms are implemented and unit-tested,
   but the loop has not been run end-to-end to produce quantitative results.
-- The earlier out-of-tree `evolve/` DGM lab (and its `pnpm evolve` harness) has
-  been removed; the technique was internalized into `src/core`.
+- The earlier out-of-tree `evolve/` DGM lab (and its `pnpm evolve` harness) and
+  the genetic-algorithm outer loop (`self-evolution evolve` / `--replay`) have
+  been removed; the technique was internalized into `src/core` and re-homed on the
+  loop-v2 in-context-RL episode.
 
 ## Contributing
 

package/dist/commands/learn.d.ts

@@ -1,3 +1,14 @@
 import { Command } from 'commander';
-export declare function registerLearnCommand(program: Command): void;
+import { type RunEpisodeOptions, type RunEpisodeResult, type RunEpisodeBusy } from '../core/self-evolution/episode-orchestrator.js';
+/**
+ * Injectable dependencies for {@link registerLearnCommand}. The ONLY seam today
+ * is `runEpisode` — the loop-v2 episode runner the autonomous `--apply` entrance
+ * invokes. It defaults to the real {@link runEpisode}; learn tests stub it so the
+ * evolve path is exercised WITHOUT spawning real agents (the orchestrator's three
+ * agents each own a `runHeadlessAgent` spawn, which the stub never reaches).
+ */
+export interface LearnCommandDeps {
+    runEpisode?: (opts: RunEpisodeOptions) => Promise<RunEpisodeResult | RunEpisodeBusy>;
+}
+export declare function registerLearnCommand(program: Command, deps?: LearnCommandDeps): void;
 //# sourceMappingURL=learn.d.ts.map