akm-cli 0.9.10 → 0.9.12

package/dist/commands/improve/improve.js

@@ -11,7 +11,7 @@ import { ConfigError, rethrowIfTestIsolationError, UsageError } from "../../core
 import { appendEvent, readEvents } from "../../core/events.js";
 import { classifyImproveAction, foldDistillSkipped } from "../../core/improve-types.js";
 import { resolveMutationTarget } from "../../core/mutation-target.js";
-import { getDbPath, getStateDbPathInDataDir } from "../../core/paths.js";
+import { getDbPath, getStashLocksDir, getStateDbPathInDataDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { openStateDatabase } from "../../core/state-db.js";
 import { info, warn, warnVerbose } from "../../core/warn.js";
@@ -481,8 +481,11 @@ function resolveImproveRunSetup(options) {
     // calling test's own at this point; we capture it before yielding the loop.
     const resolvedStateDbPath = getStateDbPathInDataDir();
     // One conservative run lock protects the complete mutation window, including
-    // triage, indexing, proposal work, maintenance, and final stash sync.
-    const lockBaseDir = primaryStashDir ? path.join(primaryStashDir, ".akm") : path.join(options.stashDir ?? ".", ".akm");
+    // triage, indexing, proposal work, maintenance, and final stash sync. Moved
+    // out of `$STASH/.akm` to `$STATE/locks/<stash>/` (itlackey/akm#890): a lock
+    // file is machine-local coordination state, not content that must travel
+    // with the bundle.
+    const lockBaseDir = getStashLocksDir(primaryStashDir ?? options.stashDir ?? ".");
     const resolvedLockPath = improveLockPath(lockBaseDir);
     const effectiveSync = { ...improveProfile.sync, ...options.sync };
     return {
@@ -1129,6 +1132,19 @@ async function runImproveStageSequence(args) {
             },
         }, eventsCtx);
     }
+    for (const item of resolvedPlan.engineUnavailable) {
+        warn(`[improve] ${item.process} skipped — it ${item.reason}.`);
+        appendEvent({
+            eventType: "improve_skipped",
+            ref: undefined,
+            metadata: {
+                strategy: selectedStrategy.name,
+                reason: "engine_unavailable",
+                process: item.process,
+                configKey: item.configKey,
+            },
+        }, eventsCtx);
+    }
     // Single prep->loop->post-loop pass, run under the invocation's lock.
     // Accumulators are direct assignments from the single pass's results.
     let preparation;
@@ -1146,6 +1162,7 @@ async function runImproveStageSequence(args) {
     // Concatenated arrays.
     const allWarnings = [];
     let deadUrls;
+    let deadUrlCoverage;
     const finalActions = [];
     {
         const runPreparation = () => runImprovePreparationStageImpl({
@@ -1228,6 +1245,9 @@ async function runImproveStageSequence(args) {
         if (postLoopResult.deadUrls !== undefined) {
             deadUrls = [...(deadUrls ?? []), ...postLoopResult.deadUrls];
         }
+        if (postLoopResult.deadUrlCoverage !== undefined) {
+            deadUrlCoverage = postLoopResult.deadUrlCoverage;
+        }
         const maintenanceActions = postLoopResult.maintenanceActions;
         if (maintenanceActions && maintenanceActions.length > 0) {
             finalActions.push(...preparation.actions, ...maintenanceActions);
@@ -1250,6 +1270,7 @@ async function runImproveStageSequence(args) {
         proposalsExpired,
         allWarnings,
         deadUrls,
+        deadUrlCoverage,
         finalActions,
     };
 }
@@ -1261,7 +1282,7 @@ async function runImproveStageSequence(args) {
 function finalizeImproveResult(args) {
     const { guidance, memorySummary, memoryCleanupPlan, strategyFilteredRefs, rawPlannedRefs, indexSnapshot, triageDrain, eventsCtx, } = args;
     const { selectedStrategy, scope, options, primaryStashDir, startMs } = args.run;
-    const { preparation, consolidation, memoryInference, graphExtraction, cycleMetrics, reflectsWithErrorContext, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, allWarnings, deadUrls, finalActions, } = args.seq;
+    const { preparation, consolidation, memoryInference, graphExtraction, cycleMetrics, reflectsWithErrorContext, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, allWarnings, deadUrls, deadUrlCoverage, finalActions, } = args.seq;
     // C1 (13-bus-factor): fold the per-ref `distill-skipped` rows (~13k/run,
     // ~91% of result_json bytes) into a bounded aggregate BEFORE persistence.
     // The metric total + per-reason breakdown are preserved on `distillSkipped`;
@@ -1326,6 +1347,10 @@ function finalizeImproveResult(args) {
         ...(preparation.extract && preparation.extract.length > 0 ? { extract: preparation.extract } : {}),
         ...(primaryStashDir !== undefined ? { evalCasesWritten: countEvalCases(primaryStashDir) } : {}),
         ...(deadUrls !== undefined && deadUrls.length > 0 ? { deadUrls } : {}),
+        // Present whenever the check ran, unlike `deadUrls` above — a clean run
+        // (zero dead links) still needs to tell the health report how much of
+        // the bundle it actually covered (#892).
+        ...(deadUrlCoverage !== undefined ? { deadUrlCoverage } : {}),
         ...(reflectsWithErrorContext > 0 ? { reflectsWithErrorContext } : {}),
         ...(memoryInference ? { memoryInference } : {}),
         ...(graphExtraction ? { graphExtraction } : {}),
@@ -1501,6 +1526,9 @@ function emitImproveCompletedEvent(result, durations, eventsCtx) {
             coverageGapCount: result.coverageGaps?.length ?? 0,
             evalCasesWritten: result.evalCasesWritten ?? 0,
             deadUrlCount: result.deadUrls?.length ?? 0,
+            deadUrlsChecked: result.deadUrlCoverage?.checked ?? 0,
+            deadUrlsTotal: result.deadUrlCoverage?.total ?? 0,
+            deadUrlsSkipped: result.deadUrlCoverage?.skipped ?? 0,
             memoryEligible: result.memorySummary.eligible,
             memoryDerived: result.memorySummary.derived,
             memoryCleanupPruneCandidates: result.memoryCleanup?.pruneCandidates.length ?? 0,

package/dist/commands/improve/loop-stages.js

@@ -569,8 +569,16 @@ export async function runImprovePostLoopStage(args) {
         resolvedPlan,
     });
     let deadUrls;
+    let deadUrlCoverage;
     if (scope.mode === "all" && primaryStashDir && actionableRefs.length > 0) {
         try {
+            // Every actionable knowledge ref is scanned for URLs — there used to be
+            // a `.slice(0, 10)` here, capping the scan to the first ten refs while
+            // `deadUrlCoverage.total` counted only those, so a real bundle reported
+            // checked === total while most refs were never looked at (#892). URL
+            // extraction (a regex over already-loaded text) is cheap; it is the
+            // network requests that are expensive, and those are bounded by
+            // `checkDeadUrls`'s concurrency limit, not by trimming what gets scanned.
             const knowledgeEntries = actionableRefs
                 .filter((r) => {
                 try {
@@ -580,7 +588,6 @@ export async function runImprovePostLoopStage(args) {
                     return false;
                 }
             })
-                .slice(0, 10)
                 .map((r) => {
                 // The URL scan needs the document body; filePath is pre-resolved on
                 // eligible refs at planning time (#591). Best-effort — an unreadable
@@ -598,8 +605,10 @@ export async function runImprovePostLoopStage(args) {
             });
             if (knowledgeEntries.length > 0) {
                 info(`[improve] checking URLs in ${knowledgeEntries.length} knowledge refs`);
-                deadUrls = await checkDeadUrls(primaryStashDir, knowledgeEntries);
-                info(`[improve] URL check complete (${deadUrls.length} dead/timeout URLs)`);
+                const urlCheck = await checkDeadUrls(primaryStashDir, knowledgeEntries);
+                deadUrls = urlCheck.deadUrls;
+                deadUrlCoverage = urlCheck.coverage;
+                info(`[improve] URL check complete (${deadUrls.length} dead/timeout URLs; checked ${urlCheck.coverage.checked} of ${urlCheck.coverage.total})`);
             }
         }
         catch {
@@ -625,6 +634,7 @@ export async function runImprovePostLoopStage(args) {
     return {
         allWarnings,
         deadUrls,
+        ...(deadUrlCoverage ? { deadUrlCoverage } : {}),
         ...(cycleMetrics ? { cycleMetrics } : {}),
         ...(maintenanceResult.memoryInference ? { memoryInference: maintenanceResult.memoryInference } : {}),
         ...(maintenanceResult.graphExtraction ? { graphExtraction: maintenanceResult.graphExtraction } : {}),

package/dist/commands/improve/preparation.js

@@ -25,7 +25,7 @@ import { isAutonomyLaneAllowed } from "./autonomy-gate.js";
 import { akmConsolidate, inspectConsolidationPool } from "./consolidate.js";
 import { computeSafeChunkSize, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
 // Eligibility / candidate-selection predicates live in ./eligibility.
-import { buildLatestFeedbackTsMap, buildLatestProposalTsMap, buildUtilityMap, dedupeRefs, findAssetFilePath, isDistillCandidateRef, isLessonCandidate, isSignalDeltaEligible, } from "./eligibility.js";
+import { buildLatestFeedbackTsMap, buildLatestProposalTsMap, buildUtilityMap, dedupeRefs, findAssetFilePath, isDistillCandidateRef, isLessonCandidate, isSignalDeltaEligible, resolveImproveScope, } from "./eligibility.js";
 import { akmExtract, countNewExtractCandidates } from "./extract.js";
 import { computeValenceScore, FEEDBACK_WEIGHT, UTILITY_WEIGHT } from "./feedback-valence.js";
 import { applyMemoryCleanup } from "./memory/memory-improve.js";
@@ -178,17 +178,20 @@ function evaluateConsolidationEligibility(args) {
     // #553 minPoolSize guard: skip consolidation when the eligible memory pool is
     // below a minimum size, rather than spending an LLM pass on a handful of
     // memories. This is an INDEPENDENT skip condition from #551's mtime pool-delta
-    // gate — either can skip. Default 500; `minPoolSize: 0` disables the guard.
-    // Evaluated against the eligible-pool count BEFORE entering the LLM loop so a
-    // skip costs ZERO LLM calls.
-    const CONSOLIDATE_DEFAULT_MIN_POOL_SIZE = 500;
+    // gate — either can skip. Default 0 (disabled) — every built-in strategy
+    // used to ship 500, which meant `akm improve --strategy consolidate`, typed
+    // by a human, silently did nothing on almost every real install. Evaluated
+    // against the eligible-pool count BEFORE entering the LLM loop so a skip
+    // costs ZERO LLM calls when an operator opts back into a floor.
+    const CONSOLIDATE_DEFAULT_MIN_POOL_SIZE = 0;
     const configuredMinPoolSize = improveProfile?.processes?.consolidate?.minPoolSize;
     const minPoolSize = typeof configuredMinPoolSize === "number" ? configuredMinPoolSize : CONSOLIDATE_DEFAULT_MIN_POOL_SIZE;
     const eligiblePoolSize = typeof memorySummary.eligible === "number" ? memorySummary.eligible : 0;
+    const userNamedStrategyOrScope = options.strategy !== undefined || resolveImproveScope(options.scope).mode === "ref";
     // volumeTriggered means the pool already exceeds the volume threshold (100),
     // so a force-triggered run never trips the pool-size guard. The guard only
     // engages when minPoolSize > 0 and the eligible pool is strictly below it.
-    const poolBelowMinSize = !volumeTriggered && minPoolSize > 0 && eligiblePoolSize < minPoolSize;
+    const poolBelowMinSize = !volumeTriggered && !userNamedStrategyOrScope && minPoolSize > 0 && eligiblePoolSize < minPoolSize;
     return {
         volumeTriggered,
         consolidationOnCooldown,

package/dist/commands/improve/reflect.js

@@ -35,7 +35,7 @@ import { lintLessonContent } from "../../core/lesson-lint.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
-import { warn } from "../../core/warn.js";
+import { warn, warnOnce } from "../../core/warn.js";
 import { lookup } from "../../indexer/indexer.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
@@ -47,7 +47,7 @@ import { collectDispatchSensitiveValues } from "../../integrations/agent/runner-
 import { isJsonSchemaKnownUnsupported, LlmCallError } from "../../llm/client.js";
 import { callStructured } from "../../llm/structured-call.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
-import { isProposalSkipped, listProposalsReadOnly, proposalContent, } from "../proposal/repository.js";
+import { isProposalSkipped, listProposalsReadOnly, proposalContent, recordGateDecision, } from "../proposal/repository.js";
 import { checkReflectSize, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
 import { deriveLessonRef } from "./distill.js";
 import { runReflectQualityJudge } from "./distill/quality-gate.js";
@@ -119,6 +119,10 @@ export const REFLECT_ALLOWED_TYPES = new Set([
     "command",
     "workflow",
 ]);
+const REFLECT_REFUSED_TYPES = new Set(["secret"]);
+function isReflectableSourceShape(content) {
+    return parseFrontmatter(content).frontmatter !== null;
+}
 /**
  * Identity / structural frontmatter fields the LLM is NEVER allowed to change.
  *
@@ -539,24 +543,15 @@ export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
     // predicate lives in `core/proposal-quality-validators` so the same check
     // also runs inside `runProposalValidators` on `proposal accept`.
     const sizeOutcome = checkReflectSize(sourceBody, cleanedBody);
+    let sizeGuardRatio;
     if (!sizeOutcome.ok) {
         const pct = (sizeOutcome.ratio * 100).toFixed(0);
         const limit = sizeOutcome.code === "EXCESSIVE_SHRINKAGE" ? "minimum 50%" : "maximum 250%";
         const cause = sizeOutcome.code === "EXCESSIVE_SHRINKAGE"
             ? "Concrete content was likely deleted."
             : "Speculative material was likely added.";
-        return {
-            content: payload.content,
-            warnings,
-            reject: {
-                // Content-policy guard hit (EXCESSIVE_SHRINKAGE / EXCESSIVE_EXPANSION).
-                // This is the guard working as designed — the LLM responded fine, we
-                // blocked the output. Routed through `content_policy_reject` so the
-                // health aggregator can split guard hits out of true LLM faults.
-                reason: "content_policy_reject",
-                error: `Reflect rejected: ${sizeOutcome.code} — proposed body is ${pct}% of source (${limit}) for ref ${targetRef}. ${cause}`,
-            },
-        };
+        warnings.push(`${sizeOutcome.code} — proposed body is ${pct}% of source (${limit}) for ref ${targetRef}. ${cause} Flagged for review.`);
+        sizeGuardRatio = { code: sizeOutcome.code, ratio: sizeOutcome.ratio };
     }
     // Reassemble final content: merged frontmatter + cleaned body.
     // When there is no frontmatter at all (no source fm and no LLM fm), emit body
@@ -570,6 +565,7 @@ export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
         content: reassembled,
         ...(hasFrontmatter ? { frontmatter: mergedFm } : {}),
         warnings,
+        ...(sizeGuardRatio ? { sizeGuardRatio } : {}),
     };
 }
 /**
@@ -636,29 +632,6 @@ function wantsJsonSchemaOutput(connection) {
 }
 /** Critique prompt injected between prior draft and refinement request (Self-Refine loop). */
 const REFLECT_CRITIQUE_PROMPT = "Your previous proposal is shown above. Review it critically and provide an improved version that is more specific, actionable, and avoids any issues with the previous attempt. Return only the improved response using the output contract from the original prompt.";
-/**
- * OpenAI-compatible thinking models charge hidden reasoning against
- * `max_tokens` before they emit the visible response. Reflect asks for a
- * machine-readable payload and requests `enableThinking: false`, but local
- * servers do not uniformly honour that flag. Keep visible-content sizing
- * separate from the allowance that lets an uncooperative thinking model reach
- * its JSON/frame envelope.
- *
- * The 2,048-token allowance exceeds the observed 1,798-token peak that
- * previously cut direct reflect responses off mid-envelope. It applies to all
- * bounded direct-LLM calls because a server's thinking behavior is not a
- * reliable capability signal; the post-processor still enforces the original
- * content-size policy.
- */
-const REFLECT_REASONING_TOKEN_HEADROOM = 2_048;
-const REFLECT_RESPONSE_ENVELOPE_CHARS = 500;
-function reflectMaxTokensForOutput(maxOutputChars) {
-    if (maxOutputChars === undefined)
-        return undefined;
-    // Divide by 3 chars/token (conservative — most models are 3.5–4), retain
-    // space for the JSON/frame wrapper, then reserve independent reasoning room.
-    return Math.ceil((maxOutputChars + REFLECT_RESPONSE_ENVELOPE_CHARS) / 3) + REFLECT_REASONING_TOKEN_HEADROOM;
-}
 function reflectLlmTelemetry(result) {
     if (!result.parsed || typeof result.parsed !== "object" || Array.isArray(result.parsed))
         return undefined;
@@ -909,7 +882,7 @@ function failureEnvelope(result, ref, engine, fallbackReason = "non_zero_exit")
  * byte-identical.
  */
 async function finalizeReflectProposal(args) {
-    const { assetContent, result, options, engineName, config, qualityGateEnabled, qualityJudgeRunner, qualityJudgeLease, feedback, stash, emitReflectFailed, onNotices, } = args;
+    const { assetContent, result, options, engineName, config, qualityGateEnabled, qualityGateSkippedNoJudge, qualityJudgeRunner, qualityJudgeLease, feedback, stash, emitReflectFailed, onNotices, } = args;
     let payload = args.payload;
     const outputTelemetry = reflectLlmTelemetry(result);
     // 7. Reflect content-preservation rails:
@@ -989,7 +962,7 @@ async function finalizeReflectProposal(args) {
     }
     // 7c. Judge the exact sanitized content that can be persisted. Fail closed
     // on cancellation, transport failure, malformed output, or an invalid score.
-    if (qualityGateEnabled) {
+    if (qualityGateEnabled && !sanitizeOutcome.sizeGuardRatio) {
         const judgeResult = await runReflectQualityJudge(config, payload.content, assetContent ?? "", feedback, options.chat, {
             runnerSelectionFrozen: true,
             ...(qualityJudgeRunner ? { llmRunner: qualityJudgeRunner } : {}),
@@ -1029,6 +1002,8 @@ async function finalizeReflectProposal(args) {
         durationMs: result.durationMs,
         emitReflectFailed,
         outputTelemetry,
+        qualityGateSkippedNoJudge,
+        sizeGuardRatio: sanitizeOutcome.sizeGuardRatio,
     });
 }
 /**
@@ -1038,7 +1013,7 @@ async function finalizeReflectProposal(args) {
  * `akmReflect`'s finalize tail.
  */
 function createReflectProposal(args) {
-    const { payload, options, stash, engineName, durationMs, emitReflectFailed, outputTelemetry } = args;
+    const { payload, options, stash, engineName, durationMs, emitReflectFailed, outputTelemetry, qualityGateSkippedNoJudge, sizeGuardRatio, } = args;
     // 8. Create the proposal. The proposal queue is the ONLY thing reflect
     // writes — promotion to a real asset is gated by `akm proposal accept`.
     //
@@ -1101,7 +1076,21 @@ function createReflectProposal(args) {
             exitCode: null,
         };
     }
-    const proposal = proposalResult;
+    let proposal = proposalResult;
+    const reviewReasons = [];
+    if (qualityGateSkippedNoJudge)
+        reviewReasons.push("no-judge-configured");
+    if (sizeGuardRatio)
+        reviewReasons.push("reflect-size-ratio");
+    if (reviewReasons.length > 0) {
+        proposal =
+            recordGateDecision(stash, proposal.id, {
+                outcome: "deferred",
+                reason: reviewReasons.join("+"),
+                gate: "reflect",
+                ...(sizeGuardRatio ? { measured: Math.round(sizeGuardRatio.ratio * 100) } : {}),
+            }, options.ctx) ?? proposal;
+    }
     appendEvent({
         eventType: "reflect_completed",
         ref: proposal.ref,
@@ -1109,6 +1098,8 @@ function createReflectProposal(args) {
             proposalId: proposal.id,
             source: "reflect",
             engine: engineName,
+            ...(qualityGateSkippedNoJudge ? { qualityGateSkippedNoJudge: true } : {}),
+            ...(sizeGuardRatio ? { sizeGuardRatio: sizeGuardRatio.code, sizeGuardRatioValue: sizeGuardRatio.ratio } : {}),
             ...(outputTelemetry ?? {}),
         },
     }, options.eventsCtx);
@@ -1299,6 +1290,19 @@ function resolveReflectRunner(options) {
     }
     return { config, activeStrategy, runnerSpec, engineName, notices };
 }
+function unsupportedTypeFailure(ref, type, detail, emitReflectFailed) {
+    emitReflectFailed("unsupported_type", "unsupported_type", ref, { type });
+    return {
+        failure: {
+            schemaVersion: 2,
+            ok: false,
+            reason: "unsupported_type",
+            error: `Reflect refused: asset type "${type}" is not supported by reflect (${detail}). Use \`akm proposal new\` or edit the file directly.`,
+            ref,
+            exitCode: null,
+        },
+    };
+}
 /**
  * Resolve the reflect target's parsed ref + current on-disk content: enforce the
  * REFLECT_ALLOWED_TYPES markdown-canonical type guard (returning a terminal
@@ -1311,27 +1315,10 @@ async function resolveReflectSource(options, stash, emitReflectFailed) {
     let parsedRef;
     if (options.ref) {
         parsedRef = parseRefInput(options.ref);
-        // 2a. Type guard — reflect only operates on asset types whose canonical
-        // shape is `frontmatter + markdown body`. Refuse non-markdown types
-        // (script / env / task) up-front so reflect never prepends YAML to a
-        // `.ts` file or rewrites a `.env` blob as prose. See REFLECT_ALLOWED_TYPES.
-        if (!REFLECT_ALLOWED_TYPES.has(parsedRef.type)) {
-            // Deterministic type-guard rejection — the LLM is never invoked. Emit
-            // with reason `unsupported_type` so the improve loop can route this to
-            // the `reflect-skipped` action bucket instead of `reflect-failed`. See
-            // `/tmp/akm-health-investigations/metrics-taxonomy-review.md` §1a
-            // ("Reflect refused asset type" — ~9% of reflect-failed events).
-            emitReflectFailed("unsupported_type", "unsupported_type", options.ref, { type: parsedRef.type });
-            return {
-                failure: {
-                    schemaVersion: 2,
-                    ok: false,
-                    reason: "unsupported_type",
-                    error: `Reflect refused: asset type "${parsedRef.type}" is not supported by reflect (only markdown-canonical types are allowed: ${[...REFLECT_ALLOWED_TYPES].sort().join(", ")}). Use \`akm proposal new\` or edit the file directly.`,
-                    ref: options.ref,
-                    exitCode: null,
-                },
-            };
+        // 2a. Refuse `secret` before any content is read — a secret's content is
+        // never touched by reflect, regardless of what it happens to look like.
+        if (REFLECT_REFUSED_TYPES.has(parsedRef.type)) {
+            return unsupportedTypeFailure(options.ref, parsedRef.type, "secret material is never read or sent to an LLM", emitReflectFailed);
         }
         if (options.assetContent !== undefined) {
             // Test seam — caller pre-loaded the source content.
@@ -1357,6 +1344,11 @@ async function resolveReflectSource(options, stash, emitReflectFailed) {
                 // Index miss is non-fatal — the agent can still propose a fresh asset.
             }
         }
+        if (!REFLECT_ALLOWED_TYPES.has(parsedRef.type)) {
+            if (assetContent === undefined || !isReflectableSourceShape(assetContent)) {
+                return unsupportedTypeFailure(options.ref, parsedRef.type, "its content is not frontmatter + markdown", emitReflectFailed);
+            }
+        }
     }
     return { assetContent, parsedRef };
 }
@@ -1393,7 +1385,7 @@ async function runReflectRefineIterations(args) {
             draftPathsToCleanup.push(iterDraftPath);
             lastDraftPath = iterDraftPath;
         }
-        const { prompt, maxOutputChars } = buildReflectPrompt({
+        const { prompt } = buildReflectPrompt({
             ...(options.ref ? { ref: options.ref } : {}),
             ...(parsedRef?.type ? { type: parsedRef.type } : {}),
             ...(parsedRef?.name ? { name: parsedRef.name } : {}),
@@ -1414,7 +1406,6 @@ async function runReflectRefineIterations(args) {
             ...(iterDraftPath ? { draftFilePath: iterDraftPath } : {}),
             ...(outputMode ? { outputMode } : {}),
         });
-        const maxTokensForLlm = reflectMaxTokensForOutput(maxOutputChars);
         let iterResult;
         if (runnerIsLlm(runnerSpec)) {
             // LLM HTTP runners cannot honor the file-write contract, so they return
@@ -1435,7 +1426,6 @@ async function runReflectRefineIterations(args) {
                 ...(options.ref ? { targetRef: options.ref } : {}),
                 allowRepair: repairAttempts === 0,
                 ...(options.chat ? { chat: options.chat } : {}),
-                ...(maxTokensForLlm !== undefined ? { maxTokens: maxTokensForLlm } : {}),
                 onNotices,
             });
         }
@@ -1638,18 +1628,11 @@ export async function akmReflect(options = {}) {
     const executionNotices = new Map();
     collectLoweringNotices(executionNotices, resolutionNotices);
     const collectExecutionNotices = (notices) => collectLoweringNotices(executionNotices, notices);
-    const qualityJudgeSelection = resolveReflectQualityJudgeRunner(config, runnerSpec, isReflectQualityGateEnabled(activeStrategy), collectExecutionNotices);
-    if (qualityJudgeSelection.enabled && !qualityJudgeSelection.runner) {
-        return {
-            schemaVersion: 2,
-            ok: false,
-            reason: "parse_error",
-            error: 'Reflect proposal quality gate rejected: score=-1, reason="no LLM configured — cannot judge, failing closed"',
-            ...(options.ref ? { ref: options.ref } : {}),
-            engine: engineName,
-            exitCode: null,
-            ...reflectNoticeFields(executionNotices),
-        };
+    let qualityJudgeSelection = resolveReflectQualityJudgeRunner(config, runnerSpec, isReflectQualityGateEnabled(activeStrategy), collectExecutionNotices);
+    const qualityGateSkippedNoJudge = qualityJudgeSelection.enabled && !qualityJudgeSelection.runner;
+    if (qualityGateSkippedNoJudge) {
+        warnOnce("reflect-quality-gate-no-judge", "Reflect proposal quality gate has no LLM configured to judge proposals (set defaults.llmEngine, or improve.strategies.<name>.processes.reflect.qualityGate.engine). Skipping the gate for this run; the proposal is queued for human review instead.");
+        qualityJudgeSelection = Object.freeze({ enabled: false, runner: undefined });
     }
     const qualityJudgeRunner = qualityJudgeSelection.runner;
     let generationLease;
@@ -1782,6 +1765,7 @@ export async function akmReflect(options = {}) {
             engineName,
             config,
             qualityGateEnabled: qualityJudgeSelection.enabled,
+            qualityGateSkippedNoJudge,
             qualityJudgeRunner,
             qualityJudgeLease,
             feedback,

package/dist/commands/lint/index.js

@@ -753,7 +753,9 @@ export async function akmLint(options = {}) {
     // classic singular/plural typo ("workflow" for "workflows"). Non-akm
     // adapters keep their own type vocabularies (see lintViaAdapter).
     if (options.typeFilter && !STASH_SUBDIRS.includes(options.typeFilter)) {
-        throw new UsageError(`lint: unknown --type "${options.typeFilter}". Valid types: ${STASH_SUBDIRS.join(", ")}.`, "INVALID_FLAG_VALUE");
+        warn(`Warning: lint --type "${options.typeFilter}" is not a recognized akm stash subdirectory — ` +
+            `valid types: ${STASH_SUBDIRS.join(", ")}. The whole bundle was validated.`);
+        options = { ...options, typeFilter: undefined };
     }
     return lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options);
 }

package/dist/commands/migrate-cli.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, EXIT_CODES, outputWithExitCode } from "../cli/shared.js";
 import { runMigrationTool } from "./migration-tool.js";
 /**
  * `akm migrate` is a thin wrapper over the standalone `akm-migrate`
@@ -23,9 +23,11 @@ export async function runMigrateSubcommand(command, args, runTool = runMigration
     catch {
         plan = undefined;
     }
-    if (plan)
-        output(command, plan);
-    else if (line)
+    if (plan) {
+        outputWithExitCode(command, plan, result.status);
+        return;
+    }
+    if (line)
         console.log(line);
     if (result.status !== EXIT_CODES.SUCCESS)
         process.exitCode = result.status;

package/dist/commands/proposal/drain-policies.js

@@ -17,6 +17,7 @@
 import fs from "node:fs";
 import { z } from "zod";
 import { UsageError } from "../../core/errors.js";
+import { warnOnce } from "../../core/warn.js";
 import { PROPOSAL_SOURCES } from "./repository.js";
 // Valid `generator` values for a drain rule are exactly the canonical proposal
 // `source` values (see {@link PROPOSAL_SOURCES} in src/commands/proposal/repository.ts). The
@@ -87,7 +88,7 @@ const DrainAcceptRuleSchema = z
     minContentLines: z.number().int().nonnegative().optional(),
     requireType: z.string().optional(),
 })
-    .strict();
+    .passthrough();
 const DrainPolicySchema = z
     .object({
     name: z.string().min(1),
@@ -95,7 +96,17 @@ const DrainPolicySchema = z
     rejectEmpty: z.boolean(),
     defer: z.array(GeneratorSchema),
 })
-    .strict();
+    .passthrough();
+function warnIgnoredPolicyKeys(filePath, label, raw, knownKeys) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return;
+    const extra = Object.keys(raw).filter((key) => !knownKeys.includes(key));
+    if (extra.length === 0)
+        return;
+    warnOnce(`drain-policy-ignored-keys:${filePath}:${label}:${extra.join(",")}`, `[proposal] Policy file "${filePath}" has ${label} field(s) akm does not recognize and ignores: ${extra.join(", ")}. Check for a typo, or the file may be written for a newer akm version.`);
+}
+const DRAIN_POLICY_KNOWN_KEYS = Object.keys(DrainPolicySchema.shape);
+const DRAIN_ACCEPT_RULE_KNOWN_KEYS = Object.keys(DrainAcceptRuleSchema.shape);
 /**
  * Resolve a `--policy <preset|path>` argument into a {@link DrainPolicy}.
  *
@@ -127,5 +138,14 @@ export function resolveDrainPolicy(arg) {
     if (!validated.success) {
         throw new UsageError(`Invalid policy file "${value}": ${validated.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ")}`, "INVALID_FLAG_VALUE");
     }
+    warnIgnoredPolicyKeys(value, "top-level", parsed, DRAIN_POLICY_KNOWN_KEYS);
+    if (parsed &&
+        typeof parsed === "object" &&
+        !Array.isArray(parsed) &&
+        Array.isArray(parsed.accept)) {
+        parsed.accept.forEach((rule, index) => {
+            warnIgnoredPolicyKeys(value, `accept[${index}]`, rule, DRAIN_ACCEPT_RULE_KNOWN_KEYS);
+        });
+    }
     return validated.data;
 }

package/dist/commands/proposal/repository.js

@@ -69,7 +69,7 @@ import { formatNewAssetDiff, formatUnifiedDiff } from "./diff-format.js";
 import { isAutomatedProposalSource, isValidProposalSource, PROPOSAL_SOURCES, } from "./proposal-types.js";
 import { hasCanonicalProposalValidator } from "./validators/proposal-validators.js";
 import { repairProposalContent, validateProposal } from "./validators/proposals.js";
-const PROMOTION_LINT_BLOCKERS = new Set(["unquoted-colon", "missing-ref", "stale-path"]);
+const PROMOTION_LINT_ISSUE_TYPES = new Set(["unquoted-colon", "missing-ref", "stale-path"]);
 // ── Proposal domain types (moved to ./proposal-types.ts, WI-9.8 KILL 1) ─────
 //
 // Proposal / ProposalStatus / ProposalPayload / ProposalReview /
@@ -1546,7 +1546,7 @@ function promotionLintBlockers(raw, assetPath, targetRoot, refType, config) {
         fix: false,
         stashRoot: targetRoot,
         extraStashRoots,
-    }).filter((finding) => PROMOTION_LINT_BLOCKERS.has(finding.issue));
+    }).filter((finding) => PROMOTION_LINT_ISSUE_TYPES.has(finding.issue));
 }
 /** Build and validate the exact stamped bytes promotion would publish, without writing. */
 export function preflightProposalPromotion(config, proposal, options = {}, ctx) {
@@ -1571,8 +1571,8 @@ export function preflightProposalPromotion(config, proposal, options = {}, ctx)
         : repairedContent;
     const lintBlockers = promotionLintBlockers(stampedContent, assetPath, target.source.path, ref.type, config);
     if (lintBlockers.length > 0) {
-        const message = lintBlockers.map((finding) => `[${finding.issue}] ${finding.detail}`).join("\n");
-        throw new UsageError(`Proposal ${proposal.id} failed lint:\n${message}`, "INVALID_PROPOSAL", "Fix or explicitly suppress the reported lint findings, then retry.");
+        const summary = lintBlockers.map((finding) => `[${finding.issue}] ${finding.detail}`).join("; ");
+        warn(`[proposal] promotion lint for ${proposal.id} found (non-blocking): ${summary}`);
     }
     return { proposal: preparedProposal, repairedContent, ref, target, assetPath, stampedContent };
 }

package/dist/commands/proposal/validators/proposal-quality-validators.js

@@ -370,14 +370,35 @@ const reflectSizeGuardValidator = {
         ];
     },
 };
+/**
+ * Report a validator's findings as advisory.
+ *
+ * These validators judge prose quality — a description that reads like a
+ * heading, an odd backtick count, a body that grew more than the reflect
+ * ratio allows. They used to BLOCK `proposal accept`, which a human types
+ * after reading the diff, and the error told that human to "fix the proposal
+ * payload and try again" — but there is no `akm proposal edit` and `accept`
+ * takes no `--force`, so the only way out was hand-editing the proposals
+ * database. A blocking check whose remedy does not exist is not a check.
+ *
+ * Structural findings stay blocking: an empty body, an unparseable ref,
+ * malformed frontmatter and a broken workflow shape genuinely cannot be
+ * written, and they live in {@link defaultProposalValidators}.
+ */
+function advisory(validator) {
+    return {
+        ...validator,
+        validate: (proposal, ctx) => validator.validate(proposal, ctx).map((finding) => ({ ...finding, severity: "warn" })),
+    };
+}
 /**
  * Full set of quality validators in registration order. Appended onto
  * {@link defaultProposalValidators} so they run inside `validateProposal` on
- * `proposal accept` automatically.
+ * `proposal accept` automatically, and report without blocking.
  */
 export const defaultProposalQualityValidators = [
     descriptionQualityValidator,
     lessonContentQualityValidator,
     sourceNotSupersededValidator,
     reflectSizeGuardValidator,
-];
+].map(advisory);