synergyspec-selfevolving 2.1.3 → 2.1.4

package/dist/core/change-readiness.js

@@ -1,6 +1,7 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import { formatChangeStatus, loadChangeContext, } from './artifact-graph/index.js';
+import { listEpisodes } from './self-evolution/episode-store.js';
 const TASK_PATTERN = /^[-*]\s+\[([\sx])\]\s*(.*)$/i;
 const REQUIRED_EVIDENCE_FILES = [
     ['specTests', 'spec-tests.md'],
@@ -45,7 +46,7 @@ export async function getChangeReadiness(projectRoot, changeName, schemaName) {
     const artifactStatus = deriveArtifactWorkflowStatus(artifactGraph);
     const taskReadiness = await readTaskReadiness(context.changeDir);
     const evidence = await readEvidenceReadiness(context.changeDir);
-    const evolution = await readEvolutionOutcome(context.changeDir);
+    const evolution = await readEvolutionOutcome(projectRoot, context.changeDir, changeName);
     const status = deriveChangeReadinessStatus(artifactStatus, taskReadiness.total, taskReadiness.completed);
     return {
         changeName,
@@ -141,18 +142,21 @@ async function readEvidenceReadiness(changeDir) {
     };
 }
 /**
- * Read the CLI-written evolution outcome for the change, if any. Defensive: any
- * missing file / parse error / unknown outcome degrades to `'not-run'` (forward
- * compatible and never throws), so `status` can always render an Evolution line.
+ * Read the CLI-written evolution outcome for the change, if any. When the manual
+ * evolution-result file is absent, fall back to the durable loop-v2 episode store
+ * so a failed `learn --apply` / self-evolution episode is not mislabeled
+ * `not-run`. Defensive: parse errors / unknown outcomes degrade to `'not-run'`
+ * (forward compatible and never throws), so `status` can always render an
+ * Evolution line.
  */
-async function readEvolutionOutcome(changeDir) {
+async function readEvolutionOutcome(projectRoot, changeDir, changeName) {
     const notRun = { status: 'not-run', promoted: false, promotedFiles: [] };
     let raw;
     try {
         raw = await fs.readFile(path.join(changeDir, 'evolution-result.json'), 'utf-8');
     }
     catch {
-        return notRun;
+        return (await readLatestEpisodeOutcome(projectRoot, changeDir, changeName)) ?? notRun;
     }
     try {
         const record = JSON.parse(raw);
@@ -189,6 +193,49 @@ async function readEvolutionOutcome(changeDir) {
         return notRun;
     }
 }
+async function readLatestEpisodeOutcome(projectRoot, changeDir, changeName) {
+    let episodes;
+    try {
+        episodes = await listEpisodes(projectRoot);
+    }
+    catch {
+        return null;
+    }
+    const resolvedChangeDir = path.resolve(changeDir);
+    const episode = episodes.find((ep) => ep.changeName === changeName || path.resolve(ep.changeDirPath) === resolvedChangeDir);
+    if (!episode)
+        return null;
+    if (episode.stage === 'errored') {
+        return {
+            status: 'error',
+            reason: episode.terminalError,
+            targetId: episode.targetId,
+            promoted: false,
+            promotedFiles: [],
+            timestamp: episode.updatedAt,
+        };
+    }
+    if (episode.stage === 'evolution-refused') {
+        return {
+            status: 'refused',
+            reason: 'evolution refused',
+            targetId: episode.targetId,
+            promoted: false,
+            promotedFiles: [],
+            timestamp: episode.updatedAt,
+        };
+    }
+    if (episode.stage === 'evolved') {
+        return {
+            status: 'promoted',
+            targetId: episode.targetId,
+            promoted: true,
+            promotedFiles: [],
+            timestamp: episode.updatedAt,
+        };
+    }
+    return null;
+}
 async function testReportRequiresPlan(testReportPath) {
     try {
         const content = await fs.readFile(testReportPath, 'utf-8');

package/dist/core/self-evolution/episode-orchestrator.d.ts

@@ -28,10 +28,12 @@
  *                                            reject-buffer entry — BOTH durably on
  *                                            disk — THEN advance 'rolled-back'.
  *        - otherwise                        → advance 'kept'.
- *   g. 演进智能体 EVOLVING AGENT           — ONLY after (f) persisted: advance the
- *      (optimizer.step)                     'evolving' marker (heartbeat) so a
- *                                            concurrent sibling sees a live holder,
- *                                            then runEvolvingAgent reads the
+ *   g. 演进智能体 EVOLVING AGENT           — ONLY after (f) persisted: require the
+ *      (optimizer.step)                     main-arm observed-GREEN evidence, then
+ *                                            advance the 'evolving' marker
+ *                                            (heartbeat) so a concurrent sibling
+ *                                            sees a live holder, then
+ *                                            runEvolvingAgent reads the
  *                                            reject-buffer FRESH from disk (so THIS
  *                                            episode's just-written entry is in its
  *                                            prompt) and either not-spawned /
@@ -39,9 +41,9 @@
  *   h. advance 'closed' + releaseInFlight  — ALWAYS, even on error.
  *
  * ORDERING GUARANTEE: the rollback + reject-buffer write are SEQUENTIAL awaits
- * that BOTH complete (and the stage reads 'rolled-back'/'kept') before
- * {@link runEvolvingAgent} is even called. (f) and (g) are never parallelized
- * and never share a Promise.all.
+ * that BOTH complete (and the stage reads 'rolled-back'/'kept') before the
+ * observed-GREEN preflight and {@link runEvolvingAgent}. (f) and (g) are never
+ * parallelized and never share a Promise.all.
  *
  * This module orchestrates; it never spawns an agent itself — the three agents
  * own their own {@link runHeadlessAgent} spawns (the `spawn` seam threads to all

package/dist/core/self-evolution/episode-orchestrator.js

@@ -1,3 +1,5 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
 import { toActionSkeleton } from '../trajectory/skeleton.js';
 import { getTrajectoryForChange } from '../trajectory/registry.js';
 import { acquireInFlight, releaseInFlight, currentPolicyVersion, readPolicyLedger, initPolicyLineage, rollbackPolicyVersion, } from './policy/policy-store.js';
@@ -6,7 +8,7 @@ import { createEpisode, advanceEpisodeStage, writeArmCapture, readEpisode, episo
 import { shouldRunCriticAgent, runCriticAgent, } from './critic-agent.js';
 import { runRewardAgentEnsemble } from './reward-aggregator.js';
 import { detectTestTamper } from './tamper-check.js';
-import { runEvolvingAgent, DEFAULT_EVOLVING_AGENT_EDIT_BUDGET, MIN_EVOLVING_AGENT_EDIT_BUDGET, } from './evolving-agent.js';
+import { runEvolvingAgent, DEFAULT_EVOLVING_AGENT_EDIT_BUDGET, MIN_EVOLVING_AGENT_EDIT_BUDGET, isArmObjectiveGreen, } from './evolving-agent.js';
 import { reconcilePrediction, summarizeCalibration, } from './policy/prediction-reconcile.js';
 /**
  * Build the 主智能体 MAIN AGENT arm `{transcript?, skeleton?, objective}` from an
@@ -183,13 +185,65 @@ function deriveEpisodeId(changeName, now) {
 /**
  * Build the `terminalError` note for a thrown step. A timeout reads identically
  * to a hard crash on disk otherwise, so a message that names a host-agent timeout
- * (the spawn timeout puts `headless agent timed out after Nms` into stderr → the
- * error message) is PREFIXED with a `timeout:` marker. A timed-out episode is
- * then distinguishable from a genuine crash in episode.json. Pure.
+ * (absolute wall: `headless agent timed out after Nms`; idle wall: `idle timeout`)
+ * is PREFIXED with a `timeout:` marker. A timed-out episode is then
+ * distinguishable from a genuine crash in episode.json. Pure.
  */
 function terminalErrorLabel(err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return /timed out/i.test(msg) ? `timeout: ${msg}` : msg;
+    return /\b(timed out|idle timeout)\b/i.test(msg) ? `timeout: ${msg}` : msg;
+}
+function observedGreenFailureReason(objective) {
+    if (!objective) {
+        return 'observed-GREEN gate: main-arm/objective.json is missing or unreadable - cannot confirm a verified green run';
+    }
+    const evidence = isArmObjectiveGreen(objective);
+    return evidence.ok ? null : `observed-GREEN gate failed: ${evidence.reason}`;
+}
+async function readMainArmObjectiveForEpisode(repoRoot, episodeId) {
+    const file = path.join(episodeDir(repoRoot, episodeId), 'main-arm', 'objective.json');
+    let raw;
+    try {
+        raw = await fs.readFile(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function runEvolvingStepIfObservedGreen(opts) {
+    const objective = Object.prototype.hasOwnProperty.call(opts, 'objective')
+        ? (opts.objective ?? null)
+        : await readMainArmObjectiveForEpisode(opts.repoRoot, opts.episodeId);
+    const gateFailure = observedGreenFailureReason(objective);
+    if (gateFailure) {
+        return { kind: 'not-spawned', reason: gateFailure };
+    }
+    if (opts.markEvolving) {
+        await advanceEpisodeStage({
+            repoRoot: opts.repoRoot,
+            episodeId: opts.episodeId,
+            stage: 'evolving',
+            patch: { evolvingHeartbeatAt: new Date().toISOString() },
+        });
+    }
+    return await runEvolvingAgent({
+        repoRoot: opts.repoRoot,
+        episodeId: opts.episodeId,
+        targetId: opts.targetId,
+        editBudget: opts.editBudget,
+        ...(opts.calibrationNote ? { calibrationNote: opts.calibrationNote } : {}),
+        spawn: opts.spawn,
+        ...(opts.agentTimeoutMs !== undefined ? { timeoutMs: opts.agentTimeoutMs } : {}),
+        ...(opts.harness ? { harness: opts.harness } : {}),
+    });
 }
 /**
  * Run ONE episode through the loop in the strict, durably-persisted order
@@ -437,16 +491,7 @@ async function runEpisodeAfterCreate(opts) {
                 ? scheduledEditBudget(await readPolicyLedger(repoRoot, targetId), editBudget)
                 : editBudget;
             const calibrationNote = await summarizeCalibration(repoRoot, targetId);
-            // Advance 'evolving' (with a heartbeat) BEFORE the spawn so a concurrent
-            // sibling reading the store sees a LIVE-but-slow holder, not a stale lock at
-            // 'kept'/'rolled-back'. runEvolvingAgent advances the terminal outcome.
-            await advanceEpisodeStage({
-                repoRoot,
-                episodeId,
-                stage: 'evolving',
-                patch: { evolvingHeartbeatAt: new Date().toISOString() },
-            });
-            evolution = await runEvolvingAgent({
+            evolution = await runEvolvingStepIfObservedGreen({
                 repoRoot,
                 episodeId,
                 targetId,
@@ -455,6 +500,8 @@ async function runEpisodeAfterCreate(opts) {
                 spawn: opts.spawn,
                 ...(opts.agentTimeoutMs !== undefined ? { timeoutMs: opts.agentTimeoutMs } : {}),
                 ...(opts.harness ? { harness: opts.harness } : {}),
+                markEvolving: true,
+                objective: opts.mainArm.objective,
             });
         }
     }
@@ -762,16 +809,7 @@ export async function resumeEpisode(opts) {
                     ? scheduledEditBudget(await readPolicyLedger(repoRoot, targetId), editBudget)
                     : editBudget;
                 const calibrationNote = await summarizeCalibration(repoRoot, targetId);
-                // Advance the 'evolving' marker (heartbeat) before the spawn, mirroring
-                // runEpisode's (g). Idempotent across a crash-resume: 'evolving' is reached
-                // from both 'rolled-back' and 'kept'.
-                await advanceEpisodeStage({
-                    repoRoot,
-                    episodeId,
-                    stage: 'evolving',
-                    patch: { evolvingHeartbeatAt: new Date().toISOString() },
-                });
-                evolution = await runEvolvingAgent({
+                evolution = await runEvolvingStepIfObservedGreen({
                     repoRoot,
                     episodeId,
                     targetId,
@@ -780,6 +818,7 @@ export async function resumeEpisode(opts) {
                     spawn: opts.spawn,
                     ...(opts.agentTimeoutMs !== undefined ? { timeoutMs: opts.agentTimeoutMs } : {}),
                     ...(opts.harness ? { harness: opts.harness } : {}),
+                    markEvolving: true,
                 });
             }
             await closeEpisodeBestEffort(repoRoot, episodeId);
@@ -802,18 +841,7 @@ export async function resumeEpisode(opts) {
                 ? scheduledEditBudget(await readPolicyLedger(repoRoot, targetId), editBudget)
                 : editBudget;
             const calibrationNote = await summarizeCalibration(repoRoot, targetId);
-            // Advance the 'evolving' marker before the spawn when resuming from the
-            // decision stage. When already at 'evolving' (a crash mid-spawn re-drive),
-            // the marker is present — skip the (now illegal) self-transition.
-            if (stage !== 'evolving') {
-                await advanceEpisodeStage({
-                    repoRoot,
-                    episodeId,
-                    stage: 'evolving',
-                    patch: { evolvingHeartbeatAt: new Date().toISOString() },
-                });
-            }
-            evolution = await runEvolvingAgent({
+            evolution = await runEvolvingStepIfObservedGreen({
                 repoRoot,
                 episodeId,
                 targetId,
@@ -822,6 +850,7 @@ export async function resumeEpisode(opts) {
                 spawn: opts.spawn,
                 ...(opts.agentTimeoutMs !== undefined ? { timeoutMs: opts.agentTimeoutMs } : {}),
                 ...(opts.harness ? { harness: opts.harness } : {}),
+                markEvolving: stage !== 'evolving',
             });
             await closeEpisodeBestEffort(repoRoot, episodeId);
         }
@@ -854,9 +883,7 @@ export async function resumeEpisode(opts) {
  * AGENT's reader uses).
  */
 async function readDiagnosisForResume(repoRoot, episodeId) {
-    const { promises: fs } = await import('node:fs');
-    const pathMod = await import('node:path');
-    const file = pathMod.join(episodeDir(repoRoot, episodeId), 'diagnosis.json');
+    const file = path.join(episodeDir(repoRoot, episodeId), 'diagnosis.json');
     let raw;
     try {
         raw = await fs.readFile(file, 'utf8');

package/dist/core/self-evolution/evolving-agent.d.ts

@@ -243,14 +243,14 @@ export declare function isArmObjectiveGreen(objective: ArmObjectiveGreenInput):
  * Run the 演进智能体 EVOLVING AGENT against an already-scored episode.
  *
  * Flow:
- *   0. Code-side refuse-to-spawn: diagnosis.abstained or no gaps ⇒ not-spawned.
- *   1. Assemble + spawn (fresh context) and parse with repair ×N; over-budget
- *      and 范围⊆诊断 (gate-3) violations are repairable too (re-prompt with the
- *      violation appended).
- *   2. Model refusal ⇒ {kind:'refused'} + a 'refused' ledger entry.
- *   3. GATES ×3 (static → observed-GREEN → 范围⊆诊断), each ANDed with the
- *      ≤ L budget and a valid prediction.
- *   4. All green ⇒ advancePolicyVersion writes the next version; episode stage
+ *   0. Code-side refuse-to-spawn: diagnosis.abstained, no gaps, or no editable
+ *      target files => not-spawned.
+ *   1. Pre-spawn gate: observed-GREEN must already be verified, because the edit
+ *      cannot change the main-arm evidence and retrying it is a category error.
+ *   2. Assemble + spawn (fresh context) and parse with repair xN; over-budget,
+ *      static, and scope-within-diagnosis violations are repairable.
+ *   3. Model refusal => {kind:'refused'} + a 'refused' ledger entry.
+ *   4. All green => advancePolicyVersion writes the next version; episode stage
  *      advances to 'evolved' (or 'evolution-refused' on refusal).
  */
 export declare function runEvolvingAgent(opts: RunEvolvingAgentOptions): Promise<RunEvolvingAgentResult>;

package/dist/core/self-evolution/evolving-agent.js

@@ -388,14 +388,14 @@ function gateFeedback(reason) {
  * Run the 演进智能体 EVOLVING AGENT against an already-scored episode.
  *
  * Flow:
- *   0. Code-side refuse-to-spawn: diagnosis.abstained or no gaps ⇒ not-spawned.
- *   1. Assemble + spawn (fresh context) and parse with repair ×N; over-budget
- *      and 范围⊆诊断 (gate-3) violations are repairable too (re-prompt with the
- *      violation appended).
- *   2. Model refusal ⇒ {kind:'refused'} + a 'refused' ledger entry.
- *   3. GATES ×3 (static → observed-GREEN → 范围⊆诊断), each ANDed with the
- *      ≤ L budget and a valid prediction.
- *   4. All green ⇒ advancePolicyVersion writes the next version; episode stage
+ *   0. Code-side refuse-to-spawn: diagnosis.abstained, no gaps, or no editable
+ *      target files => not-spawned.
+ *   1. Pre-spawn gate: observed-GREEN must already be verified, because the edit
+ *      cannot change the main-arm evidence and retrying it is a category error.
+ *   2. Assemble + spawn (fresh context) and parse with repair xN; over-budget,
+ *      static, and scope-within-diagnosis violations are repairable.
+ *   3. Model refusal => {kind:'refused'} + a 'refused' ledger entry.
+ *   4. All green => advancePolicyVersion writes the next version; episode stage
  *      advances to 'evolved' (or 'evolution-refused' on refusal).
  */
 export async function runEvolvingAgent(opts) {
@@ -435,6 +435,18 @@ export async function runEvolvingAgent(opts) {
         };
     }
     const allowedFiles = currentFiles.map((f) => f.relPath);
+    // -- 1. PRE-SPAWN GATE: observed-GREEN ------------------------------------
+    // This reads the PRE-edit MAIN arm's objective.json. A child edit cannot make
+    // red or unverified source evidence green, so fail before burning a headless
+    // evolving-agent invocation.
+    const objective = await readMainArmObjective(repoRoot, episodeId);
+    if (!objective) {
+        throw new EvolvingAgentOutputInvalid('observed-GREEN gate: main-arm/objective.json is missing or unreadable - cannot confirm a verified green run');
+    }
+    const evidence = isArmObjectiveGreen(objective);
+    if (!evidence.ok) {
+        throw new EvolvingAgentOutputInvalid(`observed-GREEN gate failed: ${evidence.reason}`);
+    }
     const rejectBuffer = await readRejectBuffer(repoRoot, targetId, REJECT_BUFFER_PROMPT_LIMIT);
     // 成功保护 DO-NOT-PRUNE: read protections + exemplars FRESH from disk (mirroring
     // the reject-buffer read just above), so the green-run-mined load-bearing
@@ -453,7 +465,7 @@ export async function runEvolvingAgent(opts) {
         doNotPrune,
         ...(opts.calibrationNote ? { calibrationNote: opts.calibrationNote } : {}),
     });
-    // ── 1. Spawn + parse with bounded repair (parse / budget / gate-3) ──────────
+    // -- 2. Spawn + parse with bounded repair (parse / budget / scope) ----------
     let feedback = null;
     let parsed = null;
     let scopeResult = null;
@@ -548,21 +560,7 @@ export async function runEvolvingAgent(opts) {
         // Unreachable on the accept path; fail closed rather than evolve out of scope.
         throw new EvolvingAgentOutputInvalid('范围⊆诊断 scope gate did not pass');
     }
-    // ── 3. POST-LOOP GATE: observed-GREEN ───────────────────────────────────────
-    // static / 范围⊆诊断 / budget / valid-prediction were all enforced inside the
-    // bounded repair loop above (a content-driven failure was repairable there).
-    // observed-GREEN runs ONCE here and is NOT repairable: it reads the PRE-edit
-    // MAIN arm's objective.json, which the edit cannot influence — re-prompting it
-    // would be a category error.
-    const objective = await readMainArmObjective(repoRoot, episodeId);
-    if (!objective) {
-        throw new EvolvingAgentOutputInvalid('observed-GREEN gate: main-arm/objective.json is missing or unreadable — cannot confirm a verified green run');
-    }
-    const evidence = isArmObjectiveGreen(objective);
-    if (!evidence.ok) {
-        throw new EvolvingAgentOutputInvalid(`observed-GREEN gate failed: ${evidence.reason}`);
-    }
-    // ── 4. Write back the next policy version. NO candidate dir / sidecar / verdict. ─
+    // -- 4. Write back the next policy version. NO candidate dir / sidecar / verdict.
     const ledgerEntry = await advancePolicyVersion({
         repoRoot,
         targetId,

package/dist/core/templates/workflows/learn.js

@@ -25,7 +25,7 @@ This is the review-and-learn step after \`/synspec:apply\` and \`/synspec:verify
 
 3. **Spawn the runner**
 
-   Use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke synergyspec-selfevolving-self-evolving for change '<name>'. Project root: <root>. Harness: <harness>. Mode: apply. Session-id: <id>. Transcript: <path>. Trigger the loop-v2 self-evolution episode autonomously, do not ask the user questions, and end with the '## Episode Verdict' block.")
+   Use the host's available general-purpose Task/subagent runner (for example \`general-purpose\` on Claude or \`general\` on hosts that expose that type), prompt: "Use Skill tool to invoke synergyspec-selfevolving-self-evolving for change '<name>'. Project root: <root>. Harness: <harness>. Mode: apply. Session-id: <id>. Transcript: <path>. Trigger the loop-v2 self-evolution episode autonomously, do not ask the user questions, and end with the '## Episode Verdict' block."
 
    Include the \`Session-id: <id>.\` / \`Transcript: <path>.\` segment only when the session handle from step 2 is known — omit it entirely when unknown.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synergyspec-selfevolving",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "synergyspec-selfevolving",
@@ -46,6 +46,7 @@
   "scripts": {
     "lint": "eslint src/",
     "build": "node build.js",
+    "build:clean": "node --input-type=module -e \"process.env.CLEAN_DIST='1'; await import('./build.js')\"",
     "dev": "tsc --watch",
     "dev:cli": "pnpm build && node bin/synergyspec-selfevolving.js",
     "test": "vitest run",
@@ -54,8 +55,8 @@
     "test:coverage": "vitest run --coverage",
     "test:postinstall": "node scripts/postinstall.js",
     "test:e2e:real-agent": "node smoking-test/run-real-agent-self-evolution-e2e.mjs --local-pack",
-    "prepare": "pnpm run build",
-    "prepublishOnly": "pnpm run build && pnpm run check:pack-version && pnpm run check:pack-contents",
+    "prepare": "pnpm run build:clean",
+    "prepublishOnly": "pnpm run build:clean && pnpm run check:pack-version && pnpm run check:pack-contents",
     "postinstall": "node scripts/postinstall.js",
     "check:docs": "node scripts/docs-check.mjs",
     "check:pack-version": "node scripts/pack-version-check.mjs",

package/schemas/spec-driven/templates/design.md

@@ -25,7 +25,8 @@ Pick a level for this change before writing the rest of this document:
 
   `## Design Level` MUST be the first `## ` heading in the file.
 
-  See the `design` artifact instruction (run: `synergyspec instructions design`) and
+  See the `design` artifact instruction (run:
+  `synergyspec-selfevolving instructions design --change <name> --json`) and
   `docs/concepts.md` for the full heuristic. If unsure between two levels, pick the
   higher one — over-classification is harmless, under-classification is not.
 -->