akm-cli 0.9.11 → 0.9.13

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/base-linter.js

@@ -132,6 +132,14 @@ function fixMissingUpdated(raw, mtime) {
     return spliceFrontmatterLine(raw, `updated: ${localDateStamp(mtime)}`) ?? raw;
 }
 // ── stale-path helpers ────────────────────────────────────────────────────────
+/**
+ * A path segment shaped like a run-time filename template rather than a
+ * literal reference: `<timestamp>`-style angle brackets, `{stamp}`/`${VAR}`
+ * braces, a `YYYYMMDD`/`HHMMSS`-style run of date-format letters, or a glob
+ * character. Such a path never exists under its literal spelling, so
+ * `stale-path` skips it instead of flagging it.
+ */
+const PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}/;
 function checkStalePath(body) {
     const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
     let match;
@@ -139,6 +147,8 @@ function checkStalePath(body) {
     // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
     while ((match = pathRe.exec(body)) !== null) {
         const candidate = match[0];
+        if (PATH_PLACEHOLDER_PATTERN.test(candidate))
+            continue;
         if (!fs.existsSync(candidate)) {
             stale.push(candidate);
         }

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/drain.js

@@ -123,6 +123,42 @@ export function classifyProposal(proposal, policy, maxDiffLines) {
 function deferReasonForSource(source) {
     return source === "distill" ? "possible-dup" : "mid-band";
 }
+/**
+ * Map a thrown error's message to one of `DrainResult.failed`'s stable reason
+ * codes, falling back to `fallback` for anything not specifically recognized.
+ * Recognizes the write-time guards a proposal can trip during promotion
+ * (see repository.ts's `promoteProposalWithLease` / `preflightProposalPromotion`).
+ */
+function categorizeDrainFailure(message, fallback) {
+    if (/target (?:changed after|was created after) proposal/.test(message))
+        return "stale-target";
+    if (/failed validation:/.test(message))
+        return "validation";
+    return fallback;
+}
+function pushDrainFailure(result, id, err, fallbackReason) {
+    const message = err instanceof Error ? err.message : String(err);
+    result.failed.push({ id, reason: categorizeDrainFailure(message, fallbackReason), detail: message });
+    return message;
+}
+/**
+ * Mirror repository.ts's `promoteProposalWithLease` stale-target guard so a
+ * dry-run preflight predicts the same refusal a real promote would hit,
+ * without writing anything. `assetPath` is the path `preflightProposalPromotion`
+ * already resolved for this proposal.
+ */
+function assertProposalTargetFresh(proposal, assetPath) {
+    const backup = fs.existsSync(assetPath) ? fs.readFileSync(assetPath) : undefined;
+    const currentHash = backup ? createHash("sha256").update(backup).digest("hex") : undefined;
+    if (proposal.beforeHash !== undefined && (!backup || currentHash !== proposal.beforeHash)) {
+        throw new Error(`Proposal target changed after proposal ${proposal.id} was created; refusing to overwrite newer content.`);
+    }
+    if (proposal.beforeHash === undefined &&
+        backup !== undefined &&
+        proposal.changes.some((change) => change.op === "create")) {
+        throw new Error(`Proposal target was created after proposal ${proposal.id} was created; refusing to overwrite newer content.`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Judgment tier (Phase 3)
 // ---------------------------------------------------------------------------
@@ -493,6 +529,7 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
         deferred: classification.deferred,
         skippedByCap: [],
         staged: [],
+        failed: [],
     };
     // A configured judgment runner makes every deferred item dispatch-eligible.
     // Validate its symbolic credentials before applying any deterministic gate,
@@ -518,7 +555,8 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                 result.rejected.push(target.id);
             }
             catch (err) {
-                warn(`[triage] reject failed for ${target.id}: ${err instanceof Error ? err.message : String(err)}`);
+                const message = pushDrainFailure(result, target.id, err, "reject-error");
+                warn(`[triage] reject failed for ${target.id}: ${message}`);
             }
         }
         // --- Accept ceiling: enforced BEFORE the promote loop ---
@@ -550,13 +588,15 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                     deterministicPromoted += 1;
                 }
                 catch (err) {
-                    warn(`[triage] promote failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+                    const message = pushDrainFailure(result, id, err, "promote-error");
+                    warn(`[triage] promote failed for ${id}: ${message}`);
                 }
             }
         }
         else if (opts.applyMode === "promote" && opts.dryRun) {
-            // Exercise the same stamped candidate and lint boundary as real promotion.
-            // Tests that omit config retain the classification-only seam.
+            // Exercise the same stamped candidate, lint, and stale-target boundary as
+            // real promotion so a dry-run's predicted promotions match what a real
+            // run would do. Tests that omit config retain the classification-only seam.
             const byId = new Map(pending.map((proposal) => [proposal.id, proposal]));
             for (const id of withinCap) {
                 try {
@@ -564,7 +604,7 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                         const proposal = byId.get(id);
                         if (!proposal)
                             throw new Error(`Proposal ${id} disappeared during drain preflight.`);
-                        preflightProposalPromotion(opts.config, proposal, {
+                        const preflight = preflightProposalPromotion(opts.config, proposal, {
                             ...(opts.target ? { target: opts.target } : {}),
                             gateDecision: {
                                 outcome: "auto-accepted",
@@ -572,12 +612,14 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                                 gate: gateLabel,
                             },
                         });
+                        assertProposalTargetFresh(proposal, preflight.assetPath);
                     }
                     result.promoted.push(id);
                     deterministicPromoted += 1;
                 }
                 catch (err) {
-                    warn(`[triage] preflight failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+                    const message = pushDrainFailure(result, id, err, "promote-error");
+                    warn(`[triage] preflight failed for ${id}: ${message}`);
                 }
             }
         }

package/dist/commands/proposal/proposal-cli.js

@@ -473,6 +473,7 @@ const proposalDrainCommand = defineJsonCommand({
             deferred: result.deferred,
             skippedByCap: result.skippedByCap,
             staged: result.staged,
+            failed: result.failed,
         });
     },
 });

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);

package/dist/commands/proposal/validators/proposals.js

@@ -26,14 +26,18 @@ export function validateProposal(proposal) {
  * structure and applies {@link repairTruncatedDescription} to a truncated
  * description when one is detected.
  *
- * Repairs performed (in order):
- *   1. Strip body lines that restate frontmatter fields as pseudo-frontmatter
- *      (e.g. `**description**: …` or `when_to_use: …` in the body).
- *   2. Remove stray body `---` horizontal-rule lines (leaving exactly the two
- *      frontmatter fences when the content has a valid frontmatter block).
- *   3. Apply {@link repairTruncatedDescription} to a truncated/hanging
+ * Repairs performed:
+ *   1. Apply {@link repairTruncatedDescription} to a truncated/hanging
  *      `description` field in the frontmatter.
  *
+ * It deliberately does NOT delete body lines. Two earlier repairs dropped
+ * every body line that restated a frontmatter key and every `---` in a body
+ * with frontmatter. Both fired inside fenced code blocks, so any asset
+ * documenting frontmatter — a note about akm, Claude Code skills, Jekyll,
+ * Hugo — was silently gutted on `proposal accept`, and the repaired bytes
+ * were written back over the original in the proposals database. A repair
+ * that can destroy content is not a repair.
+ *
  * Returns the repaired content string. When no repairs apply the input is
  * returned byte-identical so callers can use strict equality to detect
  * whether a repair actually happened.
@@ -81,19 +85,6 @@ export function repairProposalContent(content) {
             repairedLines.push(line);
             continue;
         }
-        // Repair 1: Strip pseudo-frontmatter restatements in the body.
-        // Matches lines like `**description**: …` or `when_to_use: …`.
-        if (/^\s*(\*\*|__)?\s*(description|when_to_use)\s*(\*\*|__)?\s*:/i.test(line)) {
-            // Drop the line — it is a structural defect, not user content.
-            continue;
-        }
-        // Repair 2: Remove stray `---` horizontal-rule lines in the body.
-        // We keep these only when the content has NO frontmatter (in that case
-        // `---` is a legitimate thematic break in plain-body content).
-        if (isFence && hasFrontmatter) {
-            // Drop: these are extra `---` fences beyond the two frontmatter delimiters.
-            continue;
-        }
         repairedLines.push(line);
     }
     let repaired = repairedLines.join("\n");