akm-cli 0.9.0-rc.4 → 0.9.0-rc.5

package/CHANGELOG.md

@@ -350,6 +350,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- **Improve RC stabilization.** Restored one ownership-safe whole-run lock from
+  triage through final sync; `--skip-if-locked` is a true no-op; the run deadline
+  now starts before indexing and reaches index waits, generation, reindexing, and
+  quality judges; reflect judges the sanitized final candidate with bounded
+  changed-region context; write-target selectors no longer replace durable source
+  identity; and vLLM thinking controls cannot be overridden through `extraParams`.
 - **Proposal promotion, reversion, and rejection are durable and recoverable.**
   Acceptance and reversion persist target ownership and content fingerprints,
   publish atomically across filesystem layouts, index immediately, commit exact

package/dist/assets/help/help-improve.md

@@ -67,6 +67,9 @@ Options:
                         Only process refs with recent feedback signal events
   --min-retrieval-count <n>
                         Retrieval fallback threshold when no recent feedback exists (default: 5)
+  --timeout-ms <n>      Wall-clock budget for the entire live run (default: 7200000)
+  --skip-if-locked      Exit 0 without doing work when another improve run owns
+                        the whole-run lock; no triage, indexing, events, or sync
   --json-to-stdout      Emit the full JSON result on stdout (legacy behaviour).
                         (0.8.0+: full result is recorded in the improve_runs table of
                         state.db and stdout is empty; use --json-to-stdout for the prior

package/dist/commands/improve/distill/promote-memory.js

@@ -83,7 +83,7 @@ export async function promoteMemoryToKnowledge(ctx) {
             const mergeResponse = await chat(ctx.llmConfig, [
                 { role: "system", content: "Return only valid JSON. No prose." },
                 { role: "user", content: mergePrompt },
-            ]);
+            ], ctx.signal ? { signal: ctx.signal } : undefined);
             const mergeResult = parseEmbeddedJsonResponse(mergeResponse);
             if (mergeResult?.action === "NOOP") {
                 // Existing content is authoritative — no update needed.
@@ -139,7 +139,11 @@ export async function promoteMemoryToKnowledge(ctx) {
     if (ctx.strategy?.processes?.distill?.qualityGate?.enabled ?? true) {
         // D-4 / #390: retrieve top-3 similar lessons for dedup check in judge.
         const similarLessons = await fetchSimilarLessonsFn(resolvedPromotionContent.slice(0, 500), 3);
-        const judgeResult = await runLessonQualityJudge(config, resolvedPromotionContent, assetContent ?? "", chat, similarLessons.length > 0 ? similarLessons : undefined, ctx.llmConfig);
+        const judgeResult = await runLessonQualityJudge(config, resolvedPromotionContent, assetContent ?? "", chat, {
+            ...(similarLessons.length > 0 ? { similarLessons } : {}),
+            ...(ctx.llmConfig ? { llmConfig: ctx.llmConfig } : {}),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
         if (!judgeResult.pass) {
             if (judgeResult.reviewNeeded) {
                 // Uncertainty band (2.5–3.5): queue as review_needed instead of rejecting.

package/dist/commands/improve/distill/quality-gate.js

@@ -98,37 +98,84 @@ export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
     lines.push('Return ONLY valid JSON, no prose: {"score": <average score 1-5 as float>, "reason": "<one sentence>"}');
     return lines.join("\n");
 }
-/**
- * Run the LLM-as-judge quality gate on a proposal's content.
- *
- * Exported so reflect.ts can apply the same gate to reflect proposals (R-5 / #374).
- * The selected strategy's distill/reflect quality-gate setting is resolved by
- * the caller before this function runs.
- *
- * Fail-CLOSED (07 P0-2): returns `pass: false` (score -1) on timeout, parse
- * failure, or missing LLM. Minted content that cannot be judged is rejected,
- * not passed through — an unverifiable judge must never wave content into the
- * stash. The rejection is `quality_rejected`, not `review_needed`.
- */
-export async function runLessonQualityJudge(config, lessonContent, sourceContent, chat, 
-/** D-4 / #390: top-3 similar existing lessons for dedup check. */
-similarLessons, llmConfigOverride) {
-    const llmConfig = llmConfigOverride ?? getDefaultLlmConfig(config);
+function boundedDocument(content, maxChars = 6000) {
+    if (content.length <= maxChars)
+        return content;
+    const half = Math.floor((maxChars - 80) / 2);
+    return `${content.slice(0, half)}\n\n[... middle omitted for bounded judge context ...]\n\n${content.slice(-half)}`;
+}
+function buildChangedRegion(sourceContent, candidateContent) {
+    const source = sourceContent.split("\n");
+    const candidate = candidateContent.split("\n");
+    let prefix = 0;
+    while (prefix < source.length && prefix < candidate.length && source[prefix] === candidate[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < source.length - prefix &&
+        suffix < candidate.length - prefix &&
+        source[source.length - 1 - suffix] === candidate[candidate.length - 1 - suffix]) {
+        suffix++;
+    }
+    const removed = source.slice(prefix, source.length - suffix).join("\n");
+    const added = candidate.slice(prefix, candidate.length - suffix).join("\n");
+    return boundedDocument(`Removed or replaced:\n${removed || "(none)"}\n\nAdded or replacement:\n${added || "(none)"}`);
+}
+/** Build quality criteria for revising an existing asset in place. */
+export function buildReflectJudgePrompt(candidateContent, sourceContent, feedback) {
+    return [
+        "You are evaluating a proposed revision to an existing akm asset.",
+        "",
+        "Score this revision on each criterion from 1 (poor) to 5 (excellent):",
+        "1. FEEDBACK ALIGNMENT: Does the revision address the supplied feedback or improve retrieval and clarity?",
+        "2. PRESERVATION: Does it retain the source's concrete facts, code, commands, examples, and structure without truncation?",
+        "3. QUALITY: Is the revision coherent, actionable, complete, and free of unsupported claims?",
+        "",
+        "Overlap with the source is expected and must not lower the score by itself; this is an in-place revision, not a new lesson.",
+        "",
+        "Feedback:",
+        "```",
+        (feedback.length > 0 ? feedback.join("\n") : "No explicit feedback supplied.").slice(0, 1000),
+        "```",
+        "",
+        "Source asset content:",
+        "```",
+        boundedDocument(sourceContent),
+        "```",
+        "",
+        "Proposed revision:",
+        "```",
+        boundedDocument(candidateContent),
+        "```",
+        "",
+        "Changed region:",
+        "```",
+        buildChangedRegion(sourceContent, candidateContent),
+        "```",
+        "",
+        'Return ONLY valid JSON, no prose: {"score": <average score 1-5 as float>, "reason": "<one sentence>"}',
+    ].join("\n");
+}
+async function runQualityJudge(config, prompt, chat, options = {}) {
+    const llmConfig = options.llmConfig ?? getDefaultLlmConfig(config);
     if (!llmConfig) {
         return { pass: false, score: -1, reason: "no LLM configured — cannot judge, failing closed" };
     }
-    const judgeLlmConfig = llmConfig;
-    const JUDGE_TIMEOUT_MS = 8_000;
     try {
-        const raw = await Promise.race([
-            chat(judgeLlmConfig, [
-                { role: "system", content: "Return only valid JSON. No prose." },
-                { role: "user", content: buildJudgePrompt(lessonContent, sourceContent, similarLessons) },
-            ]),
-            new Promise((_, reject) => setTimeout(() => reject(new Error("judge timeout")), JUDGE_TIMEOUT_MS)),
-        ]);
+        const raw = await chat(llmConfig, [
+            { role: "system", content: "Return only valid JSON. No prose." },
+            { role: "user", content: prompt },
+        ], {
+            enableThinking: false,
+            ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
         const parsed = parseEmbeddedJsonResponse(raw);
-        if (!parsed || typeof parsed.score !== "number") {
+        if (!parsed ||
+            typeof parsed.score !== "number" ||
+            !Number.isFinite(parsed.score) ||
+            parsed.score < 1 ||
+            parsed.score > 5 ||
+            typeof parsed.reason !== "string") {
             return { pass: false, score: -1, reason: "judge parse failed — cannot judge, failing closed" };
         }
         // D-5 / #388: Three-band system (MT-Bench arXiv:2306.05685 — ~±0.5 judge variance).
@@ -137,19 +184,35 @@ similarLessons, llmConfigOverride) {
         //   < 2.5: auto-reject (pass: false)
         const score = parsed.score;
         const reason = parsed.reason ?? "";
-        if (score >= 3.5) {
+        if (score >= 3.5)
             return { pass: true, score, reason };
-        }
-        if (score >= 2.5) {
-            // Uncertainty band: treat as failed for auto-queuing but flag for review.
+        if (score >= 2.5)
             return { pass: false, score, reason, reviewNeeded: true };
-        }
         return { pass: false, score, reason };
     }
     catch {
         return { pass: false, score: -1, reason: "judge timeout/error — cannot judge, failing closed" };
     }
 }
+/**
+ * Run the LLM-as-judge quality gate on a proposal's content.
+ *
+ * Exported so reflect.ts can apply the same gate to reflect proposals (R-5 / #374).
+ * The selected strategy's distill/reflect quality-gate setting is resolved by
+ * the caller before this function runs.
+ *
+ * Fail-CLOSED (07 P0-2): returns `pass: false` (score -1) on timeout, parse
+ * failure, or missing LLM. Minted content that cannot be judged is rejected,
+ * not passed through — an unverifiable judge must never wave content into the
+ * stash. The rejection is `quality_rejected`, not `review_needed`.
+ */
+export async function runLessonQualityJudge(config, lessonContent, sourceContent, chat, options = {}) {
+    return runQualityJudge(config, buildJudgePrompt(lessonContent, sourceContent, options.similarLessons), chat, options);
+}
+/** Judge an in-place reflect revision without applying new-lesson novelty criteria. */
+export async function runReflectQualityJudge(config, candidateContent, sourceContent, feedback, chat, options = {}) {
+    return runQualityJudge(config, buildReflectJudgePrompt(candidateContent, sourceContent, feedback), chat, options);
+}
 // ── Quality-rejection helper ─────────────────────────────────────────────────
 /**
  * Write a rejected lesson to `.akm/distill-rejected/`, append a `distill_invoked`

package/dist/commands/improve/distill.js

@@ -623,6 +623,7 @@ export async function akmDistill(options) {
         config,
         strategy: options.improveProfile,
         llmConfig: distillLlm,
+        signal: options.signal,
         chat,
         stash,
         lookup,
@@ -719,7 +720,7 @@ export async function akmDistill(options) {
         }
         // Test seam: preserve the two-arg signature so existing fake `chat`
         // functions (which return markdown strings) continue to work.
-        return chat(distillLlm, messages);
+        return chat(distillLlm, messages, options.signal ? { signal: options.signal } : undefined);
     }, null, {
         enabled: resolveProcessEnabled("distill", options.improveProfile ?? resolveImproveStrategy(undefined, config).config),
         onFallback: (evt) => {
@@ -846,7 +847,11 @@ export async function akmDistill(options) {
     if (options.improveProfile?.processes?.distill?.qualityGate?.enabled ?? true) {
         // D-4 / #390: retrieve top-3 similar lessons for dedup check in judge.
         const similarLessons = await fetchSimilarLessonsFn(content.slice(0, 500), 3);
-        const judgeResult = await runLessonQualityJudge(config, content, assetContent ?? "", chat, similarLessons.length > 0 ? similarLessons : undefined, distillLlm);
+        const judgeResult = await runLessonQualityJudge(config, content, assetContent ?? "", chat, {
+            ...(similarLessons.length > 0 ? { similarLessons } : {}),
+            ...(distillLlm ? { llmConfig: distillLlm } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
         if (!judgeResult.pass) {
             if (judgeResult.reviewNeeded) {
                 return writeQualityRejection(stash, inputRef, effectiveLessonRef, content, judgeResult.score, judgeResult.reason, {

package/dist/commands/improve/extract.js

@@ -343,7 +343,7 @@ triage, sessionIndexing, schemaSimilarityCtx, hotProbationEnabled,
 // prior row + bypass flags are threaded in from the caller. Skipping here still
 // costs ZERO LLM calls (the expensive resource #602 protects); only the cheap
 // file read is incurred.
-prior, force, 
+prior, force, signal, 
 // Stash authoring standards (convention/meta fact bodies) for non-wiki
 // output. Resolved ONCE per run by the caller and threaded in so facts are
 // not re-read per session. Empty string when none exist.
@@ -481,6 +481,7 @@ standardsContext) {
         llmRaw = await chat(getLlmConfig(), [{ role: "user", content: prompt }], {
             timeoutMs,
             responseSchema: EXTRACT_JSON_SCHEMA,
+            ...(signal ? { signal } : {}),
         });
         return llmRaw;
     }, "", { timeoutMs });
@@ -861,6 +862,8 @@ export async function akmExtract(options) {
     // prompt so facts are not re-read per session.
     const extractStandardsContext = resolveExtractStandards(stashDir);
     for (const summary of candidates) {
+        if (options.signal?.aborted)
+            break;
         // #602 — the already-extracted skip moved INTO processSession (the content
         // hash needs the session body, only available after readSession). The prior
         // row + bypass flags are threaded through; an unchanged session returns
@@ -901,7 +904,7 @@ export async function akmExtract(options) {
             sessionLockOwnership = sessionLock.ownership;
         }
         try {
-            const result = await processSession(harness, summary, stashDir, config, getLlmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, triage, sessionIndexing, schemaSimilarityCtx, hotProbationEnabled, prior, options.force === true, extractStandardsContext);
+            const result = await processSession(harness, summary, stashDir, config, getLlmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, triage, sessionIndexing, schemaSimilarityCtx, hotProbationEnabled, prior, options.force === true, options.signal, extractStandardsContext);
             sessions.push(result);
             // #626 — triage aggregation. A session reached the triage gate only when it
             // was NOT already preempted by an earlier skip (read_failed / too_short /

package/dist/commands/improve/improve-auto-accept.js

@@ -118,12 +118,11 @@ export async function runAutoAcceptGate(candidates, cfg, promoteFn = promoteProp
             continue;
         }
         try {
-            const target = resolvedConfig.defaultWriteTarget;
             const resolvedEligibilitySource = isExploration
                 ? "exploration"
                 : currentProposal?.eligibilitySource;
             const promotion = await promoteFn(cfg.stashDir, resolvedConfig, proposalId, {
-                ...(target ? { target } : {}),
+                ...(cfg.targetSelector ? { target: cfg.targetSelector } : {}),
                 eventMetadata: {
                     autoAccept: true,
                     confidence,
@@ -255,6 +254,7 @@ export function makeGateConfig(phase, shared, overrides = {}) {
         stashDir: shared.stashDir,
         config: shared.config,
         eventsCtx: shared.eventsCtx,
+        ...(shared.targetSelector ? { targetSelector: shared.targetSelector } : {}),
         ...(explorationBudgetCount !== undefined && explorationBudgetCount > 0 ? { explorationBudgetCount } : {}),
         ...overrides,
     };