akm-cli 0.9.11 → 0.9.12

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

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

package/dist/commands/read/show.js

@@ -31,7 +31,7 @@ import { NotFoundError, rethrowIfDataDirUnreadable, rethrowIfTestIsolationError,
 import { appendEvent } from "../../core/events.js";
 import { SCRIPT_EXTENSIONS } from "../../core/recognition-util.js";
 import { presentationFor } from "../../core/type-presentation.js";
-import { warn } from "../../core/warn.js";
+import { warn, warnOnce } from "../../core/warn.js";
 import { hasGraphData } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { extractGraphForSingleFile } from "../../indexer/graph/graph-extraction.js";
@@ -71,12 +71,11 @@ export async function akmShowUnified(input) {
         if (metaRef)
             return showStashMeta(metaRef);
     }
-    // Env/secret bodies have no safe fragment surface. Reject from the canonical
-    // ref namespace before auto-index or lookup can touch authored bytes. This is
-    // deliberately independent of on-disk suffix probing: secret filenames keep
-    // their natural extension, and a misspelled extensionless ref must not move
-    // the sensitive-fragment policy behind a not-found result.
-    assertSensitiveFragmentUnsupported(parseBundleRef(ref));
+    // Env/secret bodies have no safe fragment surface, and a fragment cannot
+    // widen what the env/secret renderers expose: both always omit the body
+    // (env — key names only; secret — never rendered), fragment or not. Warn
+    // and ignore the fragment rather than refusing the whole show.
+    warnSensitiveFragmentUnsupported(parseBundleRef(ref));
     // Auto-index when stale so the index is current before lookup.
     const { primarySource } = resolveReadSources();
     await ensurePrimaryIndexForRead(primarySource);
@@ -177,7 +176,7 @@ function enforceScopeOrThrow(filePath, ref, scope) {
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
     const parsed = parseBundleRef(input.ref);
-    assertSensitiveFragmentUnsupported(parsed);
+    warnSensitiveFragmentUnsupported(parsed);
     const assetParts = typeNameFromConceptId(parsed.conceptId);
     const config = loadConfig();
     const allSources = resolveSourceEntries(input.stashDir);
@@ -194,12 +193,19 @@ export async function showLocal(input) {
             `Stash "${parsed.bundle}" is not installed. Run: ${installCmd}`);
     }
     if (!indexedEntry && !resolution.owner) {
-        const unsupportedExtension = existingUnsupportedScriptExtension(assetParts, searchSources);
-        if (unsupportedExtension !== undefined) {
-            const displayExtension = unsupportedExtension || "no extension";
-            throw new NotFoundError(`Script ref "${makeBundleRef(parsed.bundle, parsed.conceptId)}" resolves to an existing file with ` +
-                `unsupported extension "${displayExtension}". Script refs must use a supported script extension: ` +
-                `${[...SCRIPT_EXTENSIONS].join(", ")}.`, "ASSET_NOT_FOUND");
+        const unrecognized = findUnrecognizedScriptSource(assetParts, searchSources);
+        if (unrecognized) {
+            const displayExtension = unrecognized.extension || "no extension";
+            warn(`Script ref "${makeBundleRef(parsed.bundle, parsed.conceptId)}" has extension "${displayExtension}", which is outside the recognized set used for indexing (${[...SCRIPT_EXTENSIONS].join(", ")}); showing it as plain text.`);
+            const fileCtx = buildFileContext(unrecognized.sourceRoot, unrecognized.path);
+            const renderer = await getRenderer("script-source");
+            if (renderer) {
+                const match = { type: "script", specificity: 0, renderer: "script-source" };
+                const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs);
+                const response = renderer.buildShowResponse(renderCtx);
+                response.name = assetParts?.name ?? response.name;
+                return response;
+            }
         }
     }
     if (!indexedEntry || !assetPath) {
@@ -242,9 +248,11 @@ export async function showLocal(input) {
             response = renderer.buildShowResponse(renderCtx);
             if (parsed.fragment !== undefined) {
                 if (!match.renderer.endsWith("-md")) {
-                    throw new UsageError(`Fragments are not supported for ${makeBundleRef(parsed.bundle, parsed.conceptId)}. Only Markdown documents support heading fragments.`, "INVALID_FLAG_VALUE");
+                    warn(`Fragment "#${parsed.fragment}" was ignored: ${makeBundleRef(parsed.bundle, parsed.conceptId)} is not a Markdown document, so heading fragments do not apply. Showing the whole asset.`);
+                }
+                else {
+                    applyMarkdownFragment(response, fileCtx.content(), parsed.fragment, presentedName);
                 }
-                applyMarkdownFragment(response, fileCtx.content(), parsed.fragment, presentedName);
             }
         }
     }
@@ -318,22 +326,22 @@ export async function showLocal(input) {
     }
     return fullResponse;
 }
-/** Reject body fragments for namespaces whose authored bytes are sensitive. */
-function assertSensitiveFragmentUnsupported(ref) {
+/**
+ * Warn and ignore body fragments for namespaces whose authored bytes are
+ * sensitive. `warnOnce`-keyed on the exact ref: `akmShowUnified` calls this
+ * before delegating to `showLocal`, which calls it again as its own
+ * defense-in-depth for callers that use `showLocal` directly — a single
+ * request must not print the same warning twice.
+ */
+function warnSensitiveFragmentUnsupported(ref) {
     if (ref.fragment === undefined)
         return;
     const type = typeNameFromConceptId(ref.conceptId)?.type;
     if (type !== "env" && type !== "secret")
         return;
-    throw new UsageError(`Fragments are not supported for ${makeBundleRef(ref.bundle, ref.conceptId)}. Sensitive ${type} assets do not expose body fragments.`, "INVALID_FLAG_VALUE");
+    warnOnce(`sensitive-fragment:${makeBundleRef(ref.bundle, ref.conceptId)}#${ref.fragment}`, `Fragment "#${ref.fragment}" was ignored: sensitive ${type} assets do not expose body fragments. Showing ${makeBundleRef(ref.bundle, ref.conceptId)} in full.`);
 }
-/**
- * Return the unsupported extension only when the exact canonical AKM script
- * path exists as a contained regular file. Physical owner arbitration runs
- * first; this is a diagnostic for its miss, never an alternate owner or
- * runnable-file classifier. No authored bytes are read.
- */
-function existingUnsupportedScriptExtension(assetParts, sources) {
+function findUnrecognizedScriptSource(assetParts, sources) {
     if (assetParts?.type !== "script")
         return undefined;
     const extension = path.extname(assetParts.name);
@@ -357,7 +365,7 @@ function existingUnsupportedScriptExtension(assetParts, sources) {
             const realCandidate = fs.realpathSync(candidate);
             if (!isWithin(realCandidate, realRoot) || !fs.statSync(realCandidate).isFile())
                 continue;
-            return extension;
+            return { extension, path: realCandidate, sourceRoot: realRoot };
         }
         catch {
             // Missing, unreadable, dangling, or otherwise unsafe paths remain normal
@@ -447,7 +455,7 @@ async function maybeExtractGraphInline(config, sourceStashDir, assetPath) {
 export async function showByRef(ref) {
     const parsed = parseBundleRef(ref);
     if (parsed.fragment !== undefined) {
-        throw new UsageError(`Fragments are not accepted by raw show: ${ref}`, "INVALID_FLAG_VALUE");
+        warn(`Fragment "#${parsed.fragment}" was ignored by raw show: ${ref}. Returning the whole file.`);
     }
     const entry = await lookupBundleRef(parsed);
     if (!entry) {
@@ -488,12 +496,15 @@ function indexedMatch(entry, renderer) {
     return { type: entry.type, specificity: Number.MAX_SAFE_INTEGER, renderer, meta: { name: entry.name } };
 }
 function buildIndexedProjectionResponse(entry, assetPath, fragment) {
-    if (fragment !== undefined && path.extname(assetPath).toLowerCase() !== ".md") {
-        throw new UsageError(`Fragments are not supported for ${entry.conceptId}. Only Markdown documents support heading fragments.`, "INVALID_FLAG_VALUE");
+    const isMarkdown = path.extname(assetPath).toLowerCase() === ".md";
+    if (fragment !== undefined && !isMarkdown) {
+        warn(`Fragment "#${fragment}" was ignored: ${entry.conceptId} is not a Markdown document, so heading fragments do not apply. Showing the whole asset.`);
     }
     const raw = fs.readFileSync(assetPath, "utf8");
     const parsed = parseFrontmatter(raw);
-    const content = fragment ? requireMarkdownSection(parsed.content, fragment, entry.name).content : parsed.content;
+    const content = fragment !== undefined && isMarkdown
+        ? requireMarkdownSection(parsed.content, fragment, entry.name).content
+        : parsed.content;
     const description = entry.document?.description ?? asNonEmptyString(parsed.data.description);
     const tags = entry.document?.tags ??
         (Array.isArray(parsed.data.tags)

package/dist/commands/registry-cli.js

@@ -4,7 +4,7 @@
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { getEffectiveRegistries, loadUserConfig, mutateConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
-import { formatRegistryUrl, hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED, registryEntryForOutput, } from "../core/registry-url.js";
+import { formatRegistryLabel, formatRegistryUrl, hasRegistryUrlCredentials, registryEntryForOutput, } from "../core/registry-url.js";
 import { warn } from "../core/warn.js";
 export const registryCommand = defineGroupCommand({
     meta: { name: "registry", description: "Manage bundle registries" },
@@ -33,7 +33,9 @@ export const registryCommand = defineGroupCommand({
             },
             async run({ args }) {
                 if (hasRegistryUrlCredentials(args.url)) {
-                    throw new UsageError(REGISTRY_CREDENTIALS_UNSUPPORTED);
+                    warn(`Registry ${formatRegistryLabel({ url: args.url, name: args.name })} was added, but its URL's ` +
+                        "username/password is ignored: authenticated registries are not supported by the built-in " +
+                        "static-index or skills-sh providers.");
                 }
                 if (!args.url.startsWith("http")) {
                     throw new UsageError("Registry URL must start with http:// or https://");