synergyspec-selfevolving 1.1.10 → 1.1.12

package/dist/core/self-evolution/learn-observation-adapter.js

@@ -22,7 +22,7 @@ import * as path from 'node:path';
 import { relativePath } from './shared.js';
 import { validateLearnEvolutionHint, } from './learn-hints.js';
 import { findCanonicalTargetsByFile, listCanonicalTargets, lookupCanonicalTarget, } from './canonical-targets.js';
-import { isCanonicalTargetEvolvable, } from './target-evolution.js';
+import { isCanonicalTargetEvolvable, explicitTargetIds, } from './target-evolution.js';
 import { detectRepoMode, resolveTargetLocalFiles } from './local-targets.js';
 import { getSchemaDir } from '../artifact-graph/resolver.js';
 import { limitText, } from '../learn.js';
@@ -288,14 +288,27 @@ export function generateEvolutionHints(report, policy) {
  * - A hint that already names a target (`affectedTargetId`) is kept iff that
  *   target is evolvable.
  * - A kind-only hint is kept iff at least one registered target of its kind is
- *   evolvable. When exactly one is evolvable, the hint is PINNED to it (its
- *   `affectedTargetId` and `thresholdKey` are filled in) so the downstream
- *   propose/gate path treats it as a concrete, single-target hint instead of an
- *   `unspecified` group.
+ *   evolvable, and is PINNED to a concrete target (its `affectedTargetId` and
+ *   `thresholdKey` are filled in) so the downstream propose/gate path treats it
+ *   as a concrete, single-target hint instead of an `unspecified` group. The pin
+ *   target is, in order:
+ *     1. the single registered target of the hint's kind named explicitly on the
+ *        CLI via `--evolve-target` (authoritative operator intent — issue #4),
+ *     2. otherwise the sole evolvable target of the kind (count heuristic).
+ *   When neither uniquely resolves (none named, and 0 or >=2 evolvable) the hint
+ *   stays kind-only/`unspecified`.
+ *
+ * The explicit-CLI pin (1) exists because `--evolve-target` previously only fed
+ * the evolvability POLICY: naming `artifact-template:tasks` left every other
+ * artifact-template target evolvable too, so the count heuristic saw >1 and never
+ * pinned — the operator's explicit choice was silently dropped and the persisted
+ * hint could not be promoted by `evolve-from-edits` (issue #4).
  *
  * When `policy` is undefined the drafts are returned unchanged (back-compat).
  * The HARD oracle/gate freeze is unaffected — oracle files are not canonical
- * targets, so no policy value can name them.
+ * targets, so no policy value can name them; a CLI-named id is pinned only when
+ * it is a registered, same-kind target that is evolvable under the resolved
+ * policy (so `--freeze-target` still wins).
  */
 function scopeHintsByPolicy(drafts, policy) {
     if (!policy)
@@ -307,24 +320,97 @@ function scopeHintsByPolicy(drafts, policy) {
                 kept.push(draft);
             continue;
         }
-        const evolvable = listCanonicalTargets({ kind: draft.affectedTargetKind }).filter((target) => isCanonicalTargetEvolvable(target.id, policy));
-        if (evolvable.length === 0)
-            continue;
-        if (evolvable.length === 1) {
-            const id = evolvable[0].id;
+        const pinId = resolveKindOnlyPinTarget(draft, policy);
+        if (pinId === null)
+            continue; // kind has no evolvable target → drop
+        if (pinId !== undefined) {
             kept.push({
                 ...draft,
-                affectedTargetId: id,
-                // `id` is already a full `<kind>:<name>` target id, so the grouping key
+                affectedTargetId: pinId,
+                // `pinId` is already a full `<kind>:<name>` target id, so the grouping key
                 // is `<id>:<changeType>` (no doubled kind prefix).
-                thresholdKey: `${id}:${draft.proposedChangeType}`,
+                thresholdKey: `${pinId}:${draft.proposedChangeType}`,
             });
             continue;
         }
-        kept.push(draft);
+        kept.push(draft); // ambiguous → keep kind-only/unspecified
     }
     return kept;
 }
+/**
+ * Decide the concrete target a kind-only hint should be pinned to under the
+ * policy. Returns the target id to pin to, `undefined` to keep the hint
+ * kind-only (ambiguous — caller leaves it `unspecified`), or `null` to drop the
+ * hint entirely (no evolvable target of its kind exists).
+ */
+function resolveKindOnlyPinTarget(draft, policy) {
+    // (1) Authoritative operator intent: a single registered, same-kind target
+    // named on the CLI via `--evolve-target` pins the hint even when config leaves
+    // other same-kind targets evolvable. `isCanonicalTargetEvolvable` honors
+    // freeze-wins, so a `--freeze-target`'d id is never pinned.
+    const namedOfKind = [...new Set(explicitTargetIds(policy.source.cliEvolve))].filter((id) => lookupCanonicalTarget(id)?.kind === draft.affectedTargetKind &&
+        isCanonicalTargetEvolvable(id, policy));
+    if (namedOfKind.length === 1)
+        return namedOfKind[0];
+    // (2) Count heuristic: pin only when exactly one target of the kind is
+    // evolvable; drop when none are; otherwise keep kind-only.
+    const evolvable = listCanonicalTargets({ kind: draft.affectedTargetKind }).filter((target) => isCanonicalTargetEvolvable(target.id, policy));
+    if (evolvable.length === 0)
+        return null;
+    if (evolvable.length === 1)
+        return evolvable[0].id;
+    return undefined;
+}
+/**
+ * Surface an UNBINDABLE kind-only evolution hint as an actionable DEFECT
+ * observation. After {@link scopeHintsByPolicy} runs, a hint that still has no
+ * `affectedTargetId` is one that could not be pinned to a concrete target (>1
+ * same-kind target evolvable and none named via `--evolve-target`) — it would
+ * surface as the `<kind>:unspecified` placeholder and yield a "0 surviving hint
+ * group" refusal that is a BINDING DEFECT, not a safe gate refusal. Emitting this
+ * is what lets the agent (and the skill) tell the two apart instead of recording a
+ * binding bug as "the gate correctly refused".
+ *
+ * Reads the SCOPED hints directly (no second pin pass), so it cannot drift from
+ * {@link scopeHintsByPolicy}. Returns `[]` when `policy` is undefined or nothing is
+ * unbindable, keeping learn output byte-identical in the common case.
+ */
+export function detectUnbindableHintObservations(hints, policy) {
+    if (!policy)
+        return [];
+    const byKind = new Map();
+    for (const hint of hints) {
+        if (hint.affectedTargetId)
+            continue; // pinned to a concrete target → fine
+        const list = byKind.get(hint.affectedTargetKind) ?? [];
+        list.push(hint);
+        byKind.set(hint.affectedTargetKind, list);
+    }
+    const observations = [];
+    for (const [kind, kindHints] of byKind) {
+        const candidates = listCanonicalTargets({ kind })
+            .filter((target) => isCanonicalTargetEvolvable(target.id, policy))
+            .map((target) => target.id);
+        const evidence = [];
+        for (const hint of kindHints) {
+            for (const item of hint.evidence) {
+                if (evidence.length >= 4)
+                    break;
+                evidence.push({ file: item.file, detail: `unbindable ${kind} hint ${hint.id}` });
+            }
+        }
+        observations.push({
+            code: 'evolution-target-unresolved',
+            severity: 'defect',
+            summary: limitText(`Evolution target unresolved — a kind-only ${kind} hint could not be pinned to a concrete target` +
+                (candidates.length > 0 ? ` (candidates: ${candidates.join(', ')})` : '') +
+                '. Pass --evolve-target <concrete> to bind it; this is a binding defect, NOT a safe gate refusal.', 300),
+            evidence,
+            tags: ['evolution', 'unbindable', 'action-required'],
+        });
+    }
+    return observations;
+}
 function inferTemplateObservation(candidate) {
     const tags = candidate.tags;
     const templateTag = tags.find((tag) => /^template:/i.test(tag));

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

@@ -68,7 +68,32 @@ export interface AutoPromoteInput {
     baselineLoss: number | null;
     /** When true, require a MEASURED improvement (history < baseline) to promote. */
     requireProvenImprovement: boolean;
+    /**
+     * This change's RAW measured code-health penalty in [0,1] (the "post" side of
+     * the default-path health gate). `null`/omitted ⇒ no health signal ⇒ the
+     * health gate does not fire (it can never block on a missing measurement).
+     */
+    healthPenalty?: number | null;
+    /**
+     * Recorded baseline code-health penalty to compare against (the "pre" side;
+     * see {@link import('./health-baseline.js').HealthBaseline}). `null`/omitted
+     * ⇒ no baseline yet ⇒ the health gate does not fire (first measured run is
+     * recorded, not gated).
+     */
+    baselineHealthPenalty?: number | null;
+    /**
+     * How much the health penalty may worsen vs the baseline before it counts as a
+     * regression. Defaults to {@link DEFAULT_HEALTH_REGRESSION_MARGIN}; absorbs
+     * measurement noise so a trivial uptick does not block the loop.
+     */
+    healthRegressionMargin?: number;
 }
+/**
+ * Default slack on the health-regression gate: a change may worsen the measured
+ * health penalty by up to this much vs the recorded baseline without being
+ * treated as a regression. Keeps measurement noise from blocking promotion.
+ */
+export declare const DEFAULT_HEALTH_REGRESSION_MARGIN = 0.05;
 export interface AutoPromoteDecision {
     promote: boolean;
     reason: string;

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

@@ -198,6 +198,12 @@ export async function rollbackCandidatePromotion(layout, candidateId, opts) {
     });
     return { candidateId, status: rolled.status, restoredFiles };
 }
+/**
+ * Default slack on the health-regression gate: a change may worsen the measured
+ * health penalty by up to this much vs the recorded baseline without being
+ * treated as a regression. Keeps measurement noise from blocking promotion.
+ */
+export const DEFAULT_HEALTH_REGRESSION_MARGIN = 0.05;
 /**
  * Pure auto-promote predicate for one-button auto-evolve. The static gate +
  * per-target switch are hard prerequisites; the fitness comparison is the
@@ -215,6 +221,21 @@ export function shouldAutoPromote(input) {
     if (!input.targetEvolvable) {
         return { promote: false, reason: 'target frozen by per-target evolution switch' };
     }
+    // Code-health regression gate (default-on health). Independent of the
+    // functional/loss history, so it fires even on the no-replay default path
+    // where `meanLoss` is null: if THIS change's measured code-health is worse
+    // than the recorded baseline by more than the margin, block — do not bake a
+    // lesson learned from a health-regressing codebase into the canonical
+    // template. No signal (penalty null) or no baseline ⇒ the gate cannot fire.
+    if (input.healthPenalty != null && input.baselineHealthPenalty != null) {
+        const margin = input.healthRegressionMargin ?? DEFAULT_HEALTH_REGRESSION_MARGIN;
+        if (input.healthPenalty > input.baselineHealthPenalty + margin) {
+            return {
+                promote: false,
+                reason: `code-health regression: penalty ${fmt(input.healthPenalty)} > baseline ${fmt(input.baselineHealthPenalty)} + margin ${fmt(margin)}`,
+            };
+        }
+    }
     const hasHistory = input.accumulatedCount > 0 && input.meanLoss !== null;
     if (input.requireProvenImprovement) {
         if (!hasHistory || input.baselineLoss === null) {

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

@@ -31,6 +31,13 @@ export interface TargetEvolutionPolicy {
         cliFreeze?: string;
     };
 }
+/**
+ * The concrete (non-`all`/`none`) target ids named in a `--evolve-target` /
+ * `--freeze-target` csv flag. Public so the learn → hint adapter can treat an
+ * explicitly named id as an authoritative pin (the policy map alone loses the
+ * distinction between "named on the CLI" and "evolvable via config default").
+ */
+export declare function explicitTargetIds(csv?: string): string[];
 /**
  * Build the effective policy from config + CLI flags. Pure; no I/O.
  */

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

@@ -11,6 +11,15 @@ function parseIds(csv) {
         none: tokens.includes('none'),
     };
 }
+/**
+ * The concrete (non-`all`/`none`) target ids named in a `--evolve-target` /
+ * `--freeze-target` csv flag. Public so the learn → hint adapter can treat an
+ * explicitly named id as an authoritative pin (the policy map alone loses the
+ * distinction between "named on the CLI" and "evolvable via config default").
+ */
+export function explicitTargetIds(csv) {
+    return parseIds(csv).ids;
+}
 /**
  * Build the effective policy from config + CLI flags. Pure; no I/O.
  */

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

@@ -9,7 +9,10 @@ Preview-only is the bare-CLI default and the explicit opt-out: run \`synergyspec
 **Default Mode: Autonomous self-evolution**
 
 - After reviewing the change, you DO the evolution. Do not stop at a report, and do not ask permission.
-- Safety is AUTOMATED, not human-gated: a canonical file is promoted ONLY when the change's test evidence is OBSERVED green (the CLI verifies the ACTUAL test run from the session trajectory, not just the authored \`test-report.md\`), the static gate passes, the target is evolvable under the per-target switch, and a rollback snapshot is taken. If evidence is missing or red, evolution stops after gating and nothing canonical is written — that is the safety floor working, not a failure; surface it and move on.
+- Safety is AUTOMATED, not human-gated: a canonical file is promoted ONLY when the change's test evidence is OBSERVED green (the CLI verifies the ACTUAL test run from the session trajectory, not just the authored \`test-report.md\`), the static gate passes, the target is evolvable under the per-target switch, and a rollback snapshot is taken.
+- When nothing canonical is written, CLASSIFY why before moving on — do not blanket-archive every no-op as "safety working":
+  - **(a) SAFE refusal (expected, not a bug):** evidence is missing or red, the target is frozen, or the static gate failed on real grounds. The floor refused to evolve on unverified / failing / out-of-scope edits. State the reason in the Evolution Result and move on.
+  - **(b) DEFECT (a tool bug to SURFACE, not archive over):** the evolution target could not be RESOLVED or BOUND (an \`evolution-target-unresolved\` observation in the learn output, or a preview target with \`targetId: null\` / \`needsDisambiguation: true\` that still will not bind after you name one concrete \`--evolve-target\`), or promotion failed for a reason that is NOT about evidence / freezing / scope. Nothing was written because the CLI COULD NOT act — not because it correctly declined. Do NOT record this as "safety working": surface it as an unresolved issue (keep an \`incident\` memory entry), name the target id that would not bind, and flag it for a fix. \`synergyspec-selfevolving status\` prints the machine-written \`Evolution:\` outcome — do not contradict it in free text.
 - Frozen gate-defining / oracle files (the gen-test/run-test oracle, schema contracts you were not asked to evolve) are NEVER touched — the CLI rejects any such edit.
 
 This run also produces neutral \`observations\` in the JSON output (reflection signals). During autonomous evolution learn persists derived evolution hints to \`.synergyspec-selfevolving/learn-handoffs/<change>/<timestamp>/hints.json\`; you then author the edit and promote it via the \`self-evolution evolve-from-edits\` command in the evolve step. The \`--agent\` flag (a headless \`claude -p\` proposer) is a cron/CI fallback ONLY — never use it when you are the running agent, and never assume \`claude\` exists on a non-Claude host.
@@ -110,7 +113,7 @@ This run also produces neutral \`observations\` in the JSON output (reflection s
 
    Unless \`--preview\` was requested, apply the learn writes directly — do not ask which to apply:
    - write the learn report (\`synergyspec-selfevolving/changes/<name>/learn-report.md\`);
-   - add the approved keep memory entries via \`synergyspec-selfevolving memory add\` (skip report-only / reject candidates);
+   - the approved keep memory entries are written FOR you by this skill's \`learn --apply --yes\` run — it stamps them with the learn-candidate tags + \`synergyspec-selfevolving-learn\` provenance. Do NOT also hand-write them with a bare \`synergyspec-selfevolving memory add\` (that loses the provenance/tag set and double-writes); reserve \`memory add\` for ad-hoc notes that are deliberately NOT learn candidates (report-only / reject candidates stay out of memory either way);
    - persist evolution hints: \`synergyspec-selfevolving learn "<name>" --persist-hints\` (this writes the hints.json you use in the evolve step).
 
    \`--preview\` is the only mode that skips these writes.
@@ -119,7 +122,7 @@ This run also produces neutral \`observations\` in the JSON output (reflection s
 
    If applying a report, write \`synergyspec-selfevolving/changes/<name>/learn-report.md\` with the preview content plus an "Applied Writes" section.
 
-   If applying memory entries, use \`synergyspec-selfevolving memory add\` with:
+   If applying memory entries MANUALLY (only when you did NOT run \`learn --apply\`, which already writes them with these tags), use \`synergyspec-selfevolving memory add\` with:
    - \`--type workflow\` for reusable workflow lessons
    - \`--type incident\` for problems to avoid
    - \`--tag synspec-learn\`
@@ -133,9 +136,11 @@ This run also produces neutral \`observations\` in the JSON output (reflection s
 
    This is the close-the-loop step: you author a concrete improvement to a canonical prompt/template and promote it onto the LOCAL installed file — no rebuild, no republish, no confirmation, no \`claude -p\`.
 
-   a. **Pick the concrete target + its local file.** From the "Skill/Template Optimization Preview" take the canonical target id and its resolved LOCAL file path (e.g. \`artifact-template:design\` → \`synergyspec-selfevolving/schemas/spec-driven/templates/design.md\`). If the preview shows a kind-only \`:unspecified\` target, choose the concrete target yourself from your analysis and pass it explicitly with \`--evolve-target\` (e.g. \`--evolve-target artifact-template:design\`).
+   a. **Pick the concrete target + its local file.** From the "Skill/Template Optimization Preview" take the canonical target id and its resolved LOCAL file path (e.g. \`artifact-template:design\` → \`synergyspec-selfevolving/schemas/spec-driven/templates/design.md\`). If the preview marks a target unbindable / needs-disambiguation (\`targetId: null\`, \`needsDisambiguation: true\`, formerly shown as \`:unspecified\`), choose ONE concrete id from its \`candidateTargetIds\` and pass it explicitly with \`--evolve-target\` (e.g. \`--evolve-target artifact-template:design\`); then re-run the preview to confirm it now binds. If it STILL will not bind after you name a single concrete \`--evolve-target\`, that is the case-(b) DEFECT above (\`evolution-target-unresolved\`) — surface it and stop; do NOT hand-edit the file to work around it.
 
-   b. **Author the edit yourself.** Reason about the exact prompt/template gap that caused the missed evidence (e.g. the design step missed a stdlib/API-shape compatibility check), then READ that local file and write its FULL improved contents. Keep the change minimal and targeted; never touch frozen oracle files.
+   b. **Author the edit yourself.** Reason about the exact prompt/template gap that caused the missed evidence (e.g. the design step missed a stdlib/API-shape compatibility check), then READ the LOCAL file the preview's \`localFiles\` resolves to and write its FULL improved contents. Keep the change minimal and targeted; never touch frozen oracle files.
+
+      Author against the path the preview gives you in \`localFiles\` (project-local). For an artifact-template / schema target on the FIRST evolution that project-local base may not exist on disk yet — the preview resolves the path read-only, and \`evolve-from-edits\` MATERIALIZES the canonical default into it (project-local override → user override → packaged default) when you promote. So if reading \`localFiles\` returns "not found", author your full new file against the canonical default content (the same base the CLI will materialize), not against a global copy. Do NOT go hunting in the GLOBAL npm install for the base (e.g. \`npm root -g\` → \`…/AppData/Roaming/npm/node_modules/synergyspec-selfevolving/schemas/…\`), and never edit anything under the global install — the materialize + promote writes land project-local under the repo (the promote write is guarded by an explicit within-repo assertion). If \`localFiles\` is empty, that target has no user-editable local surface here; treat it as the case-(b) DEFECT, not a reason to reach outside the repo.
 
    c. **Promote it in one non-interactive command** (validates → gates → observed-verified → promotes onto the local file):
    \`\`\`bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synergyspec-selfevolving",
-  "version": "1.1.10",
+  "version": "1.1.12",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "synergyspec-selfevolving",
@@ -37,6 +37,7 @@
     "schemas",
     "scripts/postinstall.js",
     "scripts/nl2repo_synergyspec-selfevolving_wrapper.py",
+    "scripts/code-health.py",
     "!dist/**/*.test.js",
     "!dist/**/__tests__",
     "!dist/**/*.map"