akm-cli 0.9.26-alpha.2 → 0.9.27-alpha.1

package/dist/commands/improve/extract-prompt.js

@@ -24,16 +24,21 @@ const EXTRACT_CANDIDATE_NAME_RE = new RegExp(EXTRACT_CANDIDATE_NAME_PATTERN);
  *
  * Shape:
  *   {
- *     "candidates": [{type, name, description, when_to_use?, body, confidence, evidence}, ...],
- *     "rationale_if_empty"?: string
+ *     "candidates": [{type, name, description, when_to_use, body, confidence, evidence}, ...],
+ *     "rationale_if_empty": string
  *   }
  *
  * `additionalProperties: false` at each level so any hallucinated keys are
- * dropped before parsing.
+ * dropped before parsing. Every property is required, as a strict structured-
+ * output provider needs (#1046), and an empty string stands for "none": a
+ * `when_to_use` only a lesson needs, a `rationale_if_empty` only an empty
+ * answer needs. Before, `when_to_use` was optional, so a model that followed
+ * the schema could leave it out of a lesson and the parser dropped the lesson
+ * (#1047).
  */
 export const EXTRACT_JSON_SCHEMA = {
     type: "object",
-    required: ["candidates"],
+    required: ["candidates", "rationale_if_empty"],
     additionalProperties: false,
     properties: {
         candidates: {
@@ -41,7 +46,7 @@ export const EXTRACT_JSON_SCHEMA = {
             description: "Zero or more durable-insight candidates extracted from the session.",
             items: {
                 type: "object",
-                required: ["type", "name", "description", "body", "confidence", "evidence"],
+                required: ["type", "name", "description", "when_to_use", "body", "confidence", "evidence"],
                 additionalProperties: false,
                 properties: {
                     type: {
@@ -62,9 +67,8 @@ export const EXTRACT_JSON_SCHEMA = {
                     },
                     when_to_use: {
                         type: "string",
-                        minLength: 15,
                         maxLength: 400,
-                        description: "Trigger sentence for the candidate; REQUIRED when type=lesson.",
+                        description: "Trigger sentence of at least 15 characters; REQUIRED when type=lesson (a lesson without one is dropped). An empty string for a memory or knowledge candidate.",
                     },
                     body: {
                         type: "string",
@@ -87,8 +91,7 @@ export const EXTRACT_JSON_SCHEMA = {
         },
         rationale_if_empty: {
             type: "string",
-            minLength: 10,
-            description: "Required when `candidates` is empty — explains why nothing rose to durable-insight level.",
+            description: "When `candidates` is empty, one sentence on why nothing rose to durable-insight level; an empty string otherwise.",
         },
     },
 };
@@ -214,10 +217,47 @@ function parseFirstJsonObject(stdout) {
     }
     return { objectFound: true };
 }
+/** The candidate the model wrote when the contract keeps it, else the first rule it breaks. */
+function readCandidate(c) {
+    const { type, name, description, body, confidence, evidence } = c;
+    if (type !== "memory" && type !== "lesson" && type !== "knowledge") {
+        return { problem: "type is not memory, lesson or knowledge" };
+    }
+    if (typeof name !== "string" || !EXTRACT_CANDIDATE_NAME_RE.test(name)) {
+        return { problem: "name is not a kebab-case slug" };
+    }
+    if (typeof description !== "string" || description.trim().length < 20) {
+        return { problem: "description is shorter than 20 characters" };
+    }
+    if (typeof body !== "string" || body.trim().length < 50)
+        return { problem: "body is shorter than 50 characters" };
+    if (typeof confidence !== "number" || !Number.isFinite(confidence))
+        return { problem: "confidence is not a number" };
+    if (typeof evidence !== "string" || evidence.trim().length < 5) {
+        return { problem: "evidence is shorter than 5 characters" };
+    }
+    // An empty string is how a strict-schema reply says "none".
+    const whenToUse = typeof c.when_to_use === "string" ? c.when_to_use.trim() : "";
+    if (type === "lesson" && whenToUse.length < 15) {
+        return { problem: "a lesson needs a when_to_use of at least 15 characters" };
+    }
+    return {
+        candidate: {
+            type,
+            name,
+            description: description.trim(),
+            ...(whenToUse ? { when_to_use: whenToUse } : {}),
+            body,
+            confidence: Math.max(0, Math.min(1, confidence)),
+            evidence: evidence.trim(),
+        },
+    };
+}
 /**
  * Parse the LLM's JSON response into a structured {@link ExtractPayload}.
  * Defensive — drops candidates that violate the shape rather than failing
- * the whole call. Returns the empty-candidates payload when nothing parses.
+ * the whole call, and names each one in `dropped` so the run can say so.
+ * Returns the empty-candidates payload when nothing parses.
  */
 export function parseExtractPayload(stdout) {
     if (!stdout || stdout.trim().length === 0) {
@@ -238,42 +278,24 @@ export function parseExtractPayload(stdout) {
     }
     const rawCandidates = obj.candidates;
     const candidates = [];
+    const dropped = [];
     for (const raw of rawCandidates) {
-        if (!raw || typeof raw !== "object")
+        if (!raw || typeof raw !== "object") {
+            dropped.push("candidate dropped: not an object");
             continue;
+        }
         const c = raw;
-        const type = c.type;
-        if (type !== "memory" && type !== "lesson" && type !== "knowledge")
-            continue;
-        if (typeof c.name !== "string" || !EXTRACT_CANDIDATE_NAME_RE.test(c.name))
-            continue;
-        if (typeof c.description !== "string" || c.description.trim().length < 20)
-            continue;
-        if (typeof c.body !== "string" || c.body.trim().length < 50)
+        const read = readCandidate(c);
+        if ("problem" in read) {
+            dropped.push(`${typeof c.type === "string" ? c.type : "candidate"}:${typeof c.name === "string" ? c.name : "(unnamed)"} dropped: ${read.problem}`);
             continue;
-        if (typeof c.confidence !== "number" || !Number.isFinite(c.confidence))
-            continue;
-        if (typeof c.evidence !== "string" || c.evidence.trim().length < 5)
-            continue;
-        if (type === "lesson") {
-            if (typeof c.when_to_use !== "string" || c.when_to_use.trim().length < 15)
-                continue;
         }
-        const confidence = Math.max(0, Math.min(1, c.confidence));
-        const candidate = {
-            type,
-            name: c.name,
-            description: c.description.trim(),
-            body: c.body,
-            confidence,
-            evidence: c.evidence.trim(),
-        };
-        if (typeof c.when_to_use === "string")
-            candidate.when_to_use = c.when_to_use.trim();
-        candidates.push(candidate);
+        candidates.push(read.candidate);
     }
     const result = { candidates };
-    if (typeof obj.rationale_if_empty === "string") {
+    if (dropped.length > 0)
+        result.dropped = dropped;
+    if (typeof obj.rationale_if_empty === "string" && obj.rationale_if_empty.trim()) {
         result.rationale_if_empty = obj.rationale_if_empty.trim();
     }
     return result;

package/dist/commands/improve/extract.js

@@ -468,7 +468,8 @@ async function processSession(run, sessionRef, gate) {
         });
     }
     const { payload } = extraction;
-    const warnings = [];
+    // A candidate the contract refused is reported, not silently lost (#1047).
+    const warnings = [...(payload.dropped ?? [])];
     // Provenance xrefs are added only after the cited session asset exists.
     const { warning, ...sessionAsset } = await maybeWriteSessionAsset(run, data);
     if (warning)

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

@@ -28,7 +28,7 @@ import { checkDeadUrls } from "../url-checker.js";
 import { isDistillCandidateRef } from "./eligibility.js";
 import { shouldSkipRef } from "./improve-strategies.js";
 import { recordLedgerAttempt, stateKey, stripBundle } from "./ledger.js";
-import { pushRecentError } from "./preparation.js";
+import { hasOnlyBarePositiveFeedback, isFlaggedSinceLastEdit, pushRecentError } from "./preparation.js";
 import { recordNoOp, resetConsecutiveNoOps } from "./salience.js";
 import { attributeStage, errMessage } from "./stage.js";
 export function prepareImproveLoopEnv(args) {
@@ -196,6 +196,8 @@ async function runLoopReflectPass(planned, env, tally) {
     }, env.eventsCtx);
     recordPlasticity(env, planned, reason === "no_change" ? "noop" : result.ok ? "changed" : undefined);
 }
+const FLAGGED_WRONG_REASON = "flagged wrong since its last edit";
+const BARE_POSITIVE_REASON = "only positive feedback, without a reason";
 async function runLoopDistillPass(planned, refType, isDistillOnly, env, tally) {
     const { options, primaryStashDir, improveProfile, resolvedPlan } = env;
     const distillSkip = shouldSkipRef(planned.ref, "distill", improveProfile);
@@ -217,6 +219,19 @@ async function runLoopDistillPass(planned, refType, isDistillOnly, env, tally) {
         return;
     if (env.distillCooledRefs.has(planned.ref) && !explicitRefScope)
         return;
+    // A memory flagged wrong and not edited since is no source for a lesson. The attempt goes in the
+    // ledger so the ref waits for newer feedback; an explicit `--scope` ref still runs.
+    if (!explicitRefScope && isFlaggedSinceLastEdit(planned, env.eventsCtx)) {
+        recordLoopAttempt(planned, env, "distill", "unchanged", FLAGGED_WRONG_REASON);
+        return recordSkip(tally, planned.ref, FLAGGED_WRONG_REASON, { env, reason: "distill_flagged_wrong" });
+    }
+    // A memory whose only recent feedback is a positive with no reason or note gives the writer nothing to distil:
+    // 10 of the 11 lessons made from one were rejected. The ledger holds it until newer feedback; an explicit `--scope`
+    // ref still runs.
+    if (!explicitRefScope && hasOnlyBarePositiveFeedback(planned, env.eventsCtx)) {
+        recordLoopAttempt(planned, env, "distill", "unchanged", BARE_POSITIVE_REASON);
+        return recordSkip(tally, planned.ref, BARE_POSITIVE_REASON, { env, reason: "distill_positive_without_reason" });
+    }
     const result = await attributeStage(resolvedPlan, "distill", () => env.distillFn({
         ref: planned.ref,
         ...(planned.itemRef ? { itemRef: planned.itemRef } : {}),

package/dist/commands/improve/memory/memory-belief.js

@@ -17,7 +17,7 @@ import { mutateFrontmatter } from "../../../core/asset/frontmatter.js";
  * An edge value as a list. A scalar string is live data (the indexer accepts
  * it), so it is promoted rather than dropped on the next write.
  */
-function readEdgeList(value) {
+export function readEdgeList(value) {
     if (Array.isArray(value))
         return value.filter((v) => typeof v === "string" && v.trim().length > 0);
     if (typeof value === "string" && value.trim())

package/dist/commands/improve/preparation.js

@@ -34,6 +34,7 @@ import { runSchemaRepairPass } from "../sources/schema-repair.js";
 import { isAutonomyLaneAllowed } from "./autonomy-gate.js";
 import { akmConsolidate, inspectConsolidationPool, loadExistingKnowledgeBodyHashes, makeConsolidateResult, } from "./consolidate.js";
 import { computeSafeChunkSize, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
+import { contentHash } from "./content-hash.js";
 import { assetTypeOf, buildUtilityMap, dedupeRefs, findAssetFilePath, isDistillCandidateRef, isLessonCandidate, resolveImproveScope, withIndexDb, } from "./eligibility.js";
 import { akmExtract, countNewExtractCandidates } from "./extract.js";
 import { computeValenceScore } from "./feedback-valence.js";
@@ -545,6 +546,51 @@ function isSignalEvent(metadata) {
     const meta = metadata;
     return meta !== undefined && (typeof meta.signal === "string" || typeof meta.note === "string");
 }
+/**
+ * Whether `candidate` was flagged wrong and not edited since. A negative
+ * feedback inside the signal window that recorded the hash of the body it
+ * judged flags it exactly when the body still has that hash, so a later write
+ * that leaves the text alone (an inference stamp, a frontmatter repair) does not
+ * lift the flag. One without a hash flags it when it is newer than the file's
+ * last write: its mtime, the one the retrieval scope reads for new material. A
+ * candidate with no readable file is not flagged.
+ */
+export function isFlaggedSinceLastEdit(candidate, eventsCtx) {
+    if (!candidate.filePath)
+        return false;
+    let editedAtMs;
+    let bodyHash;
+    try {
+        editedAtMs = fs.statSync(candidate.filePath).mtimeMs;
+        bodyHash = contentHash(fs.readFileSync(candidate.filePath, "utf8"), "body");
+    }
+    catch {
+        return false;
+    }
+    const since = new Date(Date.now() - daysToMs(FEEDBACK_SIGNAL_WINDOW_DAYS)).toISOString();
+    return readEvents({ type: "feedback", ref: keyOf(candidate), since }, eventsCtx).events.some((e) => {
+        const meta = e.metadata;
+        if (meta?.signal !== "negative")
+            return false;
+        return typeof meta.contentHash === "string" ? meta.contentHash === bodyHash : Date.parse(e.ts) > editedAtMs;
+    });
+}
+/**
+ * Whether the only feedback `candidate` has inside the signal window is positive and says nothing: no reason, no
+ * note. A bare `--positive` only records that a note helped, which gives the writer nothing to distil, so it restates
+ * the memory: 10 of the 11 lessons distilled from a memory with nothing more were rejected (the 2026-10-05 review).
+ * A candidate with no feedback in the window is not matched.
+ */
+export function hasOnlyBarePositiveFeedback(candidate, eventsCtx) {
+    const since = new Date(Date.now() - daysToMs(FEEDBACK_SIGNAL_WINDOW_DAYS)).toISOString();
+    const signals = readEvents({ type: "feedback", ref: keyOf(candidate), since }, eventsCtx).events.filter((e) => isSignalEvent(e.metadata));
+    const hasText = (value) => typeof value === "string" && value.trim() !== "";
+    return (signals.length > 0 &&
+        signals.every((e) => {
+            const meta = e.metadata;
+            return meta.signal === "positive" && !hasText(meta.reason) && !hasText(meta.note);
+        }));
+}
 /** One read of the feedback events and the ledger's reflect/distill rows. */
 export function buildSnapshotManifest(args) {
     const { eventsCtx, stashDir } = args;

package/dist/commands/improve/reflect.js

@@ -13,11 +13,13 @@
  * pre-dispatch refusals still emit both).
  */
 import fs from "node:fs";
+import path from "node:path";
+import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { DESCRIPTION_MAX_CHARS, requiresDescription } from "../../core/authoring-rules.js";
-import { resolveStashDir } from "../../core/common.js";
+import { isWithin, resolveStashDir, safeRealpath } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { generatedContentRejection } from "../../core/content-safety.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
@@ -38,6 +40,7 @@ import { isJsonSchemaKnownUnsupported, LlmCallError } from "../../llm/client.js"
 import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
 import { isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
 import { CHARS_PER_TOKEN, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
+import { contentHash } from "./content-hash.js";
 import { findAssetFilePath } from "./eligibility.js";
 import { resolveImproveExecution } from "./execution.js";
 import { recordLedgerAttempt } from "./ledger.js";
@@ -46,19 +49,29 @@ import { loadRetrievalQueries, runRetrievalRegressionGate } from "./retrieval-ga
 import { callStageOnce, errMessage, mintProposal, noticeSet, rejectedProposalContext, resolveQualityGateJudge, runReflectQualityJudge, } from "./stage.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
+/** Ends a feedback line whose event judged text the asset no longer has. */
+const EARLIER_TEXT_MARK = " (given on an earlier version of the text)";
 function readOnlyEventsContext(ctx) {
     return ctx?.db ? ctx : { ...(ctx ?? {}), readOnly: true };
 }
-/** Recent `feedback` lines for `ref` (or across all assets without one). Best-effort. */
-function readRecentFeedback(ref, eventsCtx) {
+/**
+ * Recent `feedback` lines for `ref` (or across all assets without one). Given the
+ * asset's current content, a line whose event recorded the hash of a different
+ * body is marked. Best-effort.
+ */
+function readRecentFeedback(ref, eventsCtx, assetContent) {
     try {
         const events = readEvents({ type: "feedback", ...(ref ? { ref } : {}) }, readOnlyEventsContext(eventsCtx)).events;
+        const bodyHash = assetContent === undefined ? undefined : contentHash(assetContent, "body");
         return events.slice(-(ref ? MAX_FEEDBACK_LINES : MAX_GLOBAL_FEEDBACK_LINES)).map((event) => {
             const md = event.metadata ?? {};
             const signal = typeof md.signal === "string" ? md.signal : "?";
             const note = typeof md.reason === "string" ? md.reason : typeof md.note === "string" ? md.note : "";
             const details = note ? `[${signal}] ${note}` : `[${signal}]`;
-            return !ref && event.ref ? `${event.ref} ${details}` : details;
+            const line = !ref && event.ref ? `${event.ref} ${details}` : details;
+            return bodyHash !== undefined && typeof md.contentHash === "string" && md.contentHash !== bodyHash
+                ? `${line}${EARLIER_TEXT_MARK}`
+                : line;
         });
     }
     catch {
@@ -237,7 +250,7 @@ export const REFLECT_JSON_SCHEMA = {
         frontmatterPatch: REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA,
     },
 };
-const REFLECT_UNSCOPED_JSON_SCHEMA = {
+export const REFLECT_UNSCOPED_JSON_SCHEMA = {
     type: "object",
     required: ["ref", "confidence", "frontmatterPatch"],
     additionalProperties: false,
@@ -528,6 +541,24 @@ function unsupportedTypeFailure(ref, type, detail, emitFailed) {
         },
     };
 }
+/**
+ * A proposal writes the file derived from the ref's type and name under the bundle's root. An asset indexed
+ * anywhere else (a skill's `references/a.md` is `knowledge/skills/<name>/references/a`) has nothing there, so the
+ * proposal would be a `create` and accepting it would add a second file for the ref (#1052).
+ */
+function fileOutsideLayoutFailure(ref, file, writes, emitFailed) {
+    emitFailed("unsupported_type", "file_outside_layout", ref);
+    return {
+        failure: {
+            schemaVersion: 2,
+            ok: false,
+            reason: "unsupported_type",
+            error: `Reflect refused: the file for ${ref} is ${file}, but a proposal would write ${writes}. Edit the file directly.`,
+            ref,
+            exitCode: null,
+        },
+    };
+}
 /** The target's parsed ref and current content, or a refusal for a type reflect cannot patch. */
 async function resolveReflectSource(options, stash, emitFailed) {
     if (!options.ref)
@@ -538,18 +569,21 @@ async function resolveReflectSource(options, stash, emitFailed) {
         return unsupportedTypeFailure(options.ref, parsedRef.type, "secret material is never read or sent to an LLM", emitFailed);
     }
     let assetContent = options.assetContent;
+    let assetFile;
     if (assetContent === undefined) {
         try {
             const qualifiedRef = options.itemRef ?? options.ref;
             const localFilePath = await findAssetFilePath(qualifiedRef, stash);
             if (localFilePath && fs.existsSync(localFilePath)) {
-                assetContent = fs.readFileSync(localFilePath, "utf8");
+                assetFile = localFilePath;
             }
             else {
                 const entry = await lookup(parseRefInput(qualifiedRef));
                 if (entry?.filePath && fs.existsSync(entry.filePath))
-                    assetContent = fs.readFileSync(entry.filePath, "utf8");
+                    assetFile = entry.filePath;
             }
+            if (assetFile !== undefined)
+                assetContent = fs.readFileSync(assetFile, "utf8");
         }
         catch {
             // An index miss is not fatal: reflect then has no content to patch.
@@ -559,6 +593,15 @@ async function resolveReflectSource(options, stash, emitFailed) {
         (assetContent === undefined || parseFrontmatter(assetContent).frontmatter === null)) {
         return unsupportedTypeFailure(options.ref, parsedRef.type, "its content is not frontmatter + markdown", emitFailed);
     }
+    // A file in another bundle is `createProposal`'s to refuse (#1000); this one is in the proposal's own bundle.
+    const root = path.resolve(options.target?.root ?? stash);
+    const typeDir = stashDirFor(parsedRef.type);
+    if (assetFile !== undefined && typeDir !== undefined && isWithin(assetFile, root)) {
+        const writes = assetPathForName(parsedRef.type, path.join(root, typeDir), parsedRef.name);
+        if (safeRealpath(writes) !== safeRealpath(assetFile)) {
+            return fileOutsideLayoutFailure(options.ref, assetFile, writes, emitFailed);
+        }
+    }
     return { assetContent, parsedRef };
 }
 /**
@@ -636,7 +679,7 @@ function computeReflectContentBudgetChars(promptInput, runnerSpec) {
 /** Every read-only prompt input, shared by dispatch and `--show-prompt`. */
 function gatherReflectPromptSources(options, stash, parsedRef, assetContent) {
     return {
-        feedback: readRecentFeedback(options.ref ? (options.itemRef ?? options.ref) : undefined, options.eventsCtx),
+        feedback: readRecentFeedback(options.ref ? (options.itemRef ?? options.ref) : undefined, options.eventsCtx, assetContent),
         schemaHints: buildSchemaHints(parsedRef?.type ?? "", assetContent),
         rejectedProposals: rejectedProposalContext(stash, options.ref, options.ctx, options.eventsCtx),
         standardsContext: resolveStandardsContext(options.ref, stash),

package/dist/commands/improve/retrieval-gate.js

@@ -26,7 +26,7 @@ const MAX_QUERIES = 5;
 const MAX_QUERY_CHARS = 2000;
 /** The judge sees this much of the body, as in the retrieval eval. */
 const MAX_DOC_CHARS = 1500;
-const GRADE_SCHEMA = {
+export const GRADE_SCHEMA = {
     type: "object",
     required: ["grade", "reason"],
     additionalProperties: false,

package/dist/commands/improve/session-asset.js

@@ -14,9 +14,10 @@ import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { recordWrittenPath } from "../../core/write-provenance.js";
+// Every property is required, as a strict structured-output provider needs; an empty `tags` array is none.
 export const SESSION_SUMMARY_JSON_SCHEMA = {
     type: "object",
-    required: ["summary", "key_topics"],
+    required: ["summary", "key_topics", "tags"],
     additionalProperties: false,
     properties: {
         summary: { type: "string" },
@@ -61,7 +62,7 @@ export function buildSessionSummaryPrompt(data) {
         "Transcript:",
         renderTranscriptForSummary(data.events),
         "",
-        'Respond as JSON: {"summary": string, "key_topics": string[], "tags"?: string[]}.',
+        'Respond as JSON: {"summary": string, "key_topics": string[], "tags": string[]} (an empty array for no tags).',
     ].join("\n");
 }
 /** The summary JSON, tolerating prose around it; `undefined` when nothing usable parses. */

package/dist/commands/improve/stage.js

@@ -370,7 +370,7 @@ function parseJudgeResponse(raw, keys) {
     }
     return inRange(parsed.score) ? { score: parsed.score, lowest: parsed.score, reason } : undefined;
 }
-function judgeResponseSchema(keys) {
+export function judgeResponseSchema(keys) {
     return {
         type: "object",
         required: ["scores", "reason"],

package/dist/commands/proposal/repository.js

@@ -13,12 +13,13 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { parse as parseYaml } from "yaml";
 import { ensureAkmMarkdownType } from "../../core/asset/akm-markdown.js";
 import { assetPathForName, placementTypes, stashDirFor } from "../../core/asset/asset-placement.js";
 import { isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { assembleAsset, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
-import { carryForwardBookkeepingFrontmatter, parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { carryForwardBookkeepingFrontmatter, parseFrontmatter, replaceFrontmatterBlocks, } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
@@ -883,8 +884,17 @@ function isPlainRecord(value) {
  * Stamp provenance onto a promoted asset's frontmatter: bare top-level
  * `generated` and `verified` (as OKF v0.2 spells them; `verified` accumulates),
  * and `sources` under `provenance:`, since a bare `sources:` is the wiki
- * citation-string convention. An existing frontmatter block keeps its raw body
- * bytes.
+ * citation-string convention.
+ *
+ * Source preservation: an existing frontmatter block is edited as text and not
+ * written out again through the YAML serializer, which rewraps long values,
+ * requotes and drops comments in lines the stamp never touched. The blocks of
+ * the keys the stamp sets (`generated`, `verified`, `provenance`) are removed
+ * wherever they were and written again, serialized, as the last lines of the
+ * frontmatter; every other byte, the body included, stays as written. The
+ * edited text is parsed back to confirm it holds exactly the intended mapping;
+ * when it does not (an indented `---` inside a block scalar), the frontmatter is
+ * written out again instead, as it always used to be.
  */
 function stampProposalProvenance(content, proposal, gateDecision, ctx, nowIsoStr) {
     const parsed = parseFrontmatter(content);
@@ -917,9 +927,15 @@ function stampProposalProvenance(content, proposal, gateDecision, ctx, nowIsoStr
         fm.provenance = provenance;
     else
         delete fm.provenance;
-    return parsed.frontmatter !== null
-        ? `---\n${serializeFrontmatter(fm)}\n---\n${parsed.content}`
-        : assembleAsset(fm, parsed.content);
+    if (parsed.frontmatter === null)
+        return assembleAsset(fm, parsed.content);
+    const stamped = { generated: fm.generated, verified: fm.verified };
+    if (fm.provenance !== undefined)
+        stamped.provenance = fm.provenance;
+    const edited = replaceFrontmatterBlocks(content, ["generated", "verified", "provenance"], serializeFrontmatter(stamped).split("\n"));
+    if (edited !== null && isDeepStrictEqual(parseFrontmatter(edited).data, fm))
+        return edited;
+    return `---\n${serializeFrontmatter(fm)}\n---\n${parsed.content}`;
 }
 /**
  * Validate, stamp and write an accepted proposal into its bound target, then

package/dist/core/asset/akm-markdown.js

@@ -1,11 +1,12 @@
 // 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 { isDeepStrictEqual } from "node:util";
 import { parse as parseYaml } from "yaml";
 import { localDateStamp } from "../common.js";
 import { UsageError } from "../errors.js";
 import { serializeFrontmatter } from "./asset-serialize.js";
-import { parseFrontmatterBlock, spliceFrontmatterLine } from "./frontmatter.js";
+import { parseFrontmatterBlock, replaceFrontmatterLine, spliceFrontmatterLine } from "./frontmatter.js";
 /**
  * Ensure an AKM-authored Markdown concept is also a conformant OKF concept.
  *
@@ -20,12 +21,18 @@ import { parseFrontmatterBlock, spliceFrontmatterLine } from "./frontmatter.js";
  * re-stamp on every write (which would churn timestamps and manufacture
  * needless diffs in git-backed bundles).
  *
- * Source preservation: when the type already matches and the ONLY change is
- * adding `updated`, the line is spliced into the original block textually —
- * round-tripping through the YAML serializer would drop user-authored
- * comments and normalize formatting just to contribute one field. Only a
- * document whose `type` must actually be corrected takes the re-serialize
- * path (as it always has).
+ * Source preservation: whenever the frontmatter block parses, it is edited as
+ * text and never round-tripped through the YAML serializer, which rewraps long
+ * values, reorders keys and drops comments — changes nobody made, shown to the
+ * reviewer of what may be a one-line correction. A missing `type` and a
+ * missing `updated` are each added as one line before the closing `---`, in
+ * that order; a wrong `type` is replaced on its own line. Every other byte —
+ * comments, wrapping, quoting, key order, line endings, the body — is kept as
+ * written. The edited text is parsed back to confirm it holds exactly the
+ * intended mapping; when it does not (a `type` value that spans several lines,
+ * a flow-style `{…}` block), the document is re-serialized instead, as it
+ * always used to be. A document with no frontmatter block gets a new one;
+ * malformed YAML throws.
  */
 export function ensureAkmMarkdownType(content, type, now = new Date()) {
     const block = parseFrontmatterBlock(content);
@@ -45,19 +52,36 @@ export function ensureAkmMarkdownType(content, type, now = new Date()) {
         throw new UsageError("AKM Markdown frontmatter must be a YAML mapping.", "INVALID_FLAG_VALUE");
     }
     const data = parsed;
+    const updated = localDateStamp(now);
     const needsUpdated = !("updated" in data);
-    if (data.type === type) {
-        if (!needsUpdated)
-            return content;
-        const spliced = spliceFrontmatterLine(content, `updated: ${localDateStamp(now)}`);
-        if (spliced !== null)
-            return spliced;
-        // Unreachable in practice (parseFrontmatterBlock succeeded above), but a
-        // re-serialized document beats a non-conformant one.
+    if (data.type === type && !needsUpdated)
+        return content;
+    let edited = content;
+    if (data.type !== type) {
+        edited =
+            "type" in data
+                ? replaceFrontmatterLine(edited, "type", `type: ${type}`)
+                : spliceFrontmatterLine(edited, `type: ${type}`);
     }
+    if (edited !== null && needsUpdated)
+        edited = spliceFrontmatterLine(edited, `updated: ${updated}`);
+    const intended = needsUpdated ? { ...data, type, updated } : { ...data, type };
+    if (edited !== null && parsesTo(edited, intended))
+        return edited;
+    // The text edit could not be done safely, but a re-serialized document
+    // beats a non-conformant one.
     const { type: _priorType, ...rest } = data;
     const next = { type, ...rest };
     if (needsUpdated)
-        next.updated = localDateStamp(now);
+        next.updated = updated;
     return `---\n${serializeFrontmatter(next)}\n---\n${block.content}`;
 }
+/** True when the frontmatter of `text` parses to exactly `intended`. */
+function parsesTo(text, intended) {
+    try {
+        return isDeepStrictEqual(parseYaml(parseFrontmatterBlock(text)?.frontmatter ?? ""), intended);
+    }
+    catch {
+        return false;
+    }
+}