akm-cli 0.9.0-beta.4 → 0.9.0-beta.41

package/dist/commands/lint/index.js

@@ -20,6 +20,7 @@ const STASH_SUBDIRS = [
     "lessons",
     "tasks",
     "knowledge",
+    "facts",
 ];
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function collectYamlFiles(dir) {
@@ -85,7 +86,8 @@ export function akmLint(options = {}) {
     const fix = options.fix ?? false;
     const fixed = [];
     const flagged = [];
-    for (const subdir of STASH_SUBDIRS) {
+    const dirsToScan = options.typeFilter ? STASH_SUBDIRS.filter((d) => d === options.typeFilter) : STASH_SUBDIRS;
+    for (const subdir of dirsToScan) {
         const dirPath = path.join(stashRoot, subdir);
         // Tasks are .yml files; everything else is .md
         const files = subdir === "tasks" ? collectYamlFiles(dirPath) : collectMarkdownFiles(dirPath);
@@ -97,7 +99,9 @@ export function akmLint(options = {}) {
                 if (entry.isDirectory()) {
                     const subdirIssues = linter.lintDirectory(path.join(dirPath, entry.name), stashRoot);
                     for (const issue of subdirIssues) {
-                        if (issue.fixed) {
+                        // Tristate-safe: only `true` counts as fixed; `false` and "failed"
+                        // are both flagged.
+                        if (issue.fixed === true) {
                             fixed.push(issue);
                         }
                         else {
@@ -108,6 +112,9 @@ export function akmLint(options = {}) {
             }
         }
         for (const filePath of files) {
+            // Skip registry-cached read-only files — --fix must not mutate them.
+            if (filePath.includes("/.cache/") || filePath.includes("/registry/"))
+                continue;
             const relPath = path.relative(stashRoot, filePath);
             let raw;
             try {
@@ -142,10 +149,11 @@ export function akmLint(options = {}) {
                     fileDeleted = true;
                     fixed.push(issue);
                 }
-                else if (issue.fixed) {
+                else if (issue.fixed === true) {
                     fixed.push(issue);
                 }
                 else {
+                    // fixed === false (not fixable / no fix requested) or "failed" (fix attempted but threw)
                     flagged.push(issue);
                 }
             }
@@ -159,16 +167,26 @@ export function akmLint(options = {}) {
     // findings go into `flagged`, never `fixed`.
     const envRoots = [stashRoot, ...extraStashRoots];
     for (const root of envRoots) {
-        const dir = path.join(root, "env");
-        if (!fs.existsSync(dir))
-            continue;
-        for (const envPath of collectEnvFiles(dir)) {
-            const baseName = path.basename(envPath, ".env");
-            // "default" (or empty) maps to ".env" → env:default
-            const ref = baseName === "" ? "env:default" : `env:${baseName}`;
-            const relPath = path.relative(root, envPath);
-            for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
-                flagged.push(issue);
+        // The `env` assets live under `env/` (ref prefix `env:`); whole-file
+        // `secret` assets live under `secrets/` (canonical ref prefix `secret:`,
+        // singular). Map the scan directory to its canonical ref prefix so the
+        // finding's `Ref:` field matches what `akm show`/`akm secret` accept.
+        for (const { scanSubdir, refPrefix } of [
+            { scanSubdir: "env", refPrefix: "env" },
+            { scanSubdir: "secrets", refPrefix: "secret" },
+        ]) {
+            const dir = path.join(root, scanSubdir);
+            if (!fs.existsSync(dir))
+                continue;
+            for (const envPath of collectEnvFiles(dir)) {
+                const baseName = path.basename(envPath, ".env");
+                // A dotfile literally named `.env` has an empty baseName — use the full
+                // basename so it doesn't collide with `default.env` → refPrefix:default.
+                const ref = baseName === "" ? `${refPrefix}:.env` : `${refPrefix}:${baseName}`;
+                const relPath = path.relative(root, envPath);
+                for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
+                    flagged.push(issue);
+                }
             }
         }
     }

package/dist/commands/lint/memory-linter.js

@@ -33,7 +33,7 @@ export class MemoryLinter extends BaseLinter {
                         file: ctx.relPath,
                         issue: "orphaned-stub",
                         detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
-                        fixed: false,
+                        fixed: "failed",
                     });
                 }
                 // Signal caller to skip remaining checks via a sentinel issue

package/dist/commands/lint/registry.js

@@ -4,6 +4,7 @@
 import { AgentLinter } from "./agent-linter.js";
 import { CommandLinter } from "./command-linter.js";
 import { DefaultLinter } from "./default-linter.js";
+import { FactLinter } from "./fact-linter.js";
 import { KnowledgeLinter } from "./knowledge-linter.js";
 import { MemoryLinter } from "./memory-linter.js";
 import { SkillLinter } from "./skill-linter.js";
@@ -18,15 +19,19 @@ const LINTERS = [
     new KnowledgeLinter(),
     new SkillLinter(),
     new TaskLinter(),
-    new DefaultLinter(),
+    new FactLinter(),
 ];
+// Single shared DefaultLinter instance — used both as the explicit "lessons"
+// handler and as the fallback for any unrecognised asset type.
+const DEFAULT_LINTER = new DefaultLinter();
 const LINTER_MAP = new Map();
 for (const linter of LINTERS) {
     for (const t of linter.types) {
         LINTER_MAP.set(t, linter);
     }
 }
-const DEFAULT_LINTER = new DefaultLinter();
+// Register "lessons" explicitly so there is only one DefaultLinter instance.
+LINTER_MAP.set("lessons", DEFAULT_LINTER);
 /**
  * Return the appropriate linter for the given stash subdirectory name.
  * Falls back to `DefaultLinter` for unknown types.

package/dist/commands/lint/task-linter.js

@@ -28,9 +28,9 @@ export class TaskLinter extends BaseLinter {
         if (!("schedule" in ctx.data) || typeof ctx.data.schedule !== "string" || ctx.data.schedule.trim() === "") {
             missing.push("schedule");
         }
-        // enabled: must be present (boolean — value of false is valid)
-        if (!("enabled" in ctx.data)) {
-            missing.push("enabled");
+        // enabled: must be present AND a boolean (value of false is valid, but "yes" / 1 are not)
+        if (!("enabled" in ctx.data) || typeof ctx.data.enabled !== "boolean") {
+            missing.push("enabled (must be a boolean)");
         }
         // At least one of: prompt, workflow, or command
         const hasTarget = "prompt" in ctx.data || "workflow" in ctx.data || "command" in ctx.data;

package/dist/commands/lint/workflow-linter.js

@@ -2,6 +2,7 @@
 // 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 fs from "node:fs";
+import { parseWorkflow } from "../../workflows/parser.js";
 import { BaseLinter } from "./base-linter.js";
 const PLACEHOLDER_STRINGS = ["Describe what this workflow accomplishes", "Example Workflow"];
 /**
@@ -32,7 +33,7 @@ export class WorkflowLinter extends BaseLinter {
                         file: ctx.relPath,
                         issue: "placeholder-stub",
                         detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
-                        fixed: false,
+                        fixed: "failed",
                     });
                 }
                 return issues;
@@ -44,6 +45,30 @@ export class WorkflowLinter extends BaseLinter {
                 fixed: false,
             });
         }
+        const isReadOnly = ctx.filePath.includes("/.cache/") || ctx.filePath.includes("/registry/");
+        if (!isReadOnly) {
+            try {
+                const result = parseWorkflow(ctx.raw, { path: ctx.filePath });
+                if (!result.ok) {
+                    for (const err of result.errors ?? []) {
+                        issues.push({
+                            file: ctx.relPath,
+                            issue: "invalid-workflow-structure",
+                            detail: err.message ?? String(err),
+                            fixed: false,
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "invalid-workflow-structure",
+                    detail: `workflow parser error: ${e instanceof Error ? e.message : String(e)}`,
+                    fixed: false,
+                });
+            }
+        }
         return issues;
     }
     #checkPlaceholderStub(body) {

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

@@ -45,6 +45,10 @@ export const PERSONAL_STASH = {
         { generator: "reflect", maxDiffLines: 80 },
         // Consolidate within the diff band; mid-band lands in `defer` below.
         { generator: "consolidate", maxDiffLines: 200 },
+        // Recombine: accept only confirmed type:lesson proposals (promoted by the
+        // recombine confidence gate) within the diff band. type:hypothesis proposals
+        // have no matching rule here and stay pending for manual review.
+        { generator: "recombine", requireType: "lesson", maxDiffLines: 200 },
     ],
     rejectEmpty: true,
     // Mid-band consolidate, distill duplicates, and contradiction escalations are
@@ -83,6 +87,7 @@ const DrainAcceptRuleSchema = z
     generator: GeneratorSchema,
     maxDiffLines: z.number().int().positive().optional(),
     minContentLines: z.number().int().nonnegative().optional(),
+    requireType: z.string().optional(),
 })
     .strict();
 const DrainPolicySchema = z

package/dist/commands/proposal/drain.js

@@ -80,7 +80,16 @@ export function classifyProposal(proposal, policy, maxDiffLines) {
     if (policy.rejectEmpty && isEmptyDiff(proposal)) {
         return { verdict: "reject", reason: "empty diff", gate: { reason: "empty-diff" } };
     }
-    const rule = policy.accept.find((r) => r.generator === proposal.source);
+    const rule = policy.accept.find((r) => {
+        if (r.generator !== proposal.source)
+            return false;
+        if (r.requireType !== undefined) {
+            const fm = parseFrontmatter(proposal.payload.content ?? "").data;
+            if (typeof fm.type !== "string" || fm.type !== r.requireType)
+                return false;
+        }
+        return true;
+    });
     if (rule) {
         const lines = contentLineCount(content);
         const body = contentBodyLineCount(content);
@@ -361,6 +370,13 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
     // — these are re-stamped `no-judge-configured` when no runner resolves them.
     const needsJudge = new Set();
     for (const proposal of pending) {
+        // Do NOT reclassify a proposal that was already conclusively stamped
+        // `auto-rejected` by a prior gate run (e.g. the improve confidence gate).
+        // Overwriting an authoritative rejection with `auto-accepted` would corrupt
+        // the audit trail and silently promote content the gate explicitly rejected.
+        // Such proposals remain pending for manual review (or TTL expiry).
+        if (proposal.gateDecision?.outcome === "auto-rejected")
+            continue;
         const decision = classifyProposal(proposal, opts.policy, opts.maxDiffLines);
         if (decision === null)
             continue;

package/dist/commands/proposal/proposal.js

@@ -75,6 +75,11 @@ export async function akmProposalAccept(options) {
             source: result.proposal.source,
             ...(result.proposal.sourceRun !== undefined ? { sourceRun: result.proposal.sourceRun } : {}),
             assetPath: result.assetPath,
+            // Attribution tagging: carry the eligibility lane from the proposal record
+            // onto the promoted event so accept outcomes can be sliced by lane.
+            ...(result.proposal.eligibilitySource !== undefined
+                ? { eligibilitySource: result.proposal.eligibilitySource }
+                : {}),
         },
     });
     return {

package/dist/commands/proposal/propose.js

@@ -18,6 +18,7 @@ import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
 import { resolveStashDir } from "../../core/common.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
+import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { runAgent, } from "../../integrations/agent/index.js";
 import { resolveProcessAgentProfile } from "../../integrations/agent/config.js";
 import { buildProposePrompt, parseAgentProposalPayload } from "../../integrations/agent/prompts.js";
@@ -93,10 +94,14 @@ export async function akmPropose(options) {
     // directly using its file tools rather than returning JSON via stdout.
     const draftFilePath = import("node:os").then((os) => import("node:path").then((path) => path.join(os.tmpdir(), `akm-propose-${options.type}-${options.name.replace(/[^a-z0-9_-]/gi, "_")}-${Date.now()}.md`)));
     const resolvedDraftPath = await draftFilePath;
+    // Standards "rulebook" for this target — wiki schema (wiki page) or stash
+    // convention/meta facts (non-wiki asset); empty when neither fires.
+    const standardsContext = resolveStandardsContext(`${options.type}:${options.name}`, stash);
     const prompt = buildProposePrompt({
         type: options.type,
         name: options.name,
         task: options.task,
+        ...(standardsContext.trim() ? { standardsContext } : {}),
         draftFilePath: resolvedDraftPath,
     });
     // 4. Spawn the agent.

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

@@ -59,6 +59,7 @@
  */
 // ── Reflect-size guard ───────────────────────────────────────────────────────
 import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { DESCRIPTION_MAX_CHARS, DESCRIPTION_MIN_CHARS, WHEN_TO_USE_MAX_CHARS, WHEN_TO_USE_MIN_CHARS, } from "../../../core/authoring-rules.js";
 import { detectTruncatedDescription, TRUNCATION_TRAILING_WORDS } from "../../../core/text-truncation.js";
 // ── Description / when_to_use shape ─────────────────────────────────────────
 export const HEADING_FRAGMENT_PATTERNS = [
@@ -80,10 +81,10 @@ export function isValidDescription(value, inputRef, options = {}) {
     const v = value.trim();
     if (!v)
         return { ok: false, reason: "description is empty" };
-    if (v.length < 20)
-        return { ok: false, reason: `description is too short (${v.length} chars; need ≥20)` };
-    if (v.length > 400)
-        return { ok: false, reason: `description is too long (${v.length} chars; max 400)` };
+    if (v.length < DESCRIPTION_MIN_CHARS)
+        return { ok: false, reason: `description is too short (${v.length} chars; need ≥${DESCRIPTION_MIN_CHARS})` };
+    if (v.length > DESCRIPTION_MAX_CHARS)
+        return { ok: false, reason: `description is too long (${v.length} chars; max ${DESCRIPTION_MAX_CHARS})` };
     if (/^\s*[\d#*\->`]/.test(v))
         return { ok: false, reason: "description starts with a digit or markdown marker" };
     const last = v.slice(-1);
@@ -133,10 +134,10 @@ export function isValidWhenToUse(value, inputRef) {
     const v = value.trim();
     if (!v)
         return { ok: false, reason: "when_to_use is empty" };
-    if (v.length < 15)
-        return { ok: false, reason: `when_to_use is too short (${v.length} chars; need ≥15)` };
-    if (v.length > 400)
-        return { ok: false, reason: `when_to_use is too long (${v.length} chars; max 400)` };
+    if (v.length < WHEN_TO_USE_MIN_CHARS)
+        return { ok: false, reason: `when_to_use is too short (${v.length} chars; need ≥${WHEN_TO_USE_MIN_CHARS})` };
+    if (v.length > WHEN_TO_USE_MAX_CHARS)
+        return { ok: false, reason: `when_to_use is too long (${v.length} chars; max ${WHEN_TO_USE_MAX_CHARS})` };
     if (/^when working with\b/i.test(v))
         return { ok: false, reason: "when_to_use is the circular 'When working with ...' fallback" };
     const refTail = inputRef.split(":").pop()?.toLowerCase() ?? "";

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

@@ -50,7 +50,8 @@ import { makeAssetRef, parseAssetRef } from "../../../core/asset/asset-ref.js";
 import { resolveAssetPathFromName, TYPE_DIRS } from "../../../core/asset/asset-spec.js";
 import { NotFoundError, UsageError } from "../../../core/errors.js";
 import { appendEvent } from "../../../core/events.js";
-import { getStateDbPath, getStateProposal, hasImportedFsProposals, insertProposalIfAbsent, listStateProposalIdsByPrefix, listStateProposals, openStateDatabase, recordFsProposalsImport, upsertProposal, } from "../../../core/state-db.js";
+import { getStateDbPath, getStateProposal, hasImportedFsProposals, insertProposalIfAbsent, listStateProposalIdsByPrefix, listStateProposals, openStateDatabase, recordFsProposalsImport, upsertProposal, withImmediateTransaction, } from "../../../core/state-db.js";
+import { repairTruncatedDescription } from "../../../core/text-truncation.js";
 import { warn } from "../../../core/warn.js";
 import { commitWriteTargetBoundary, formatRefForMessage, resolveWriteTarget, writeAssetToSource, } from "../../../core/write-source.js";
 import { runProposalValidators } from "./proposal-validators.js";
@@ -74,6 +75,8 @@ export const PROPOSAL_SOURCES = [
     "consolidate",
     "extract",
     "improve",
+    "recombine",
+    "procedural",
     // Semi-automated / tool-driven.
     "feedback",
     // Human-initiated / CLI-driven.
@@ -91,6 +94,8 @@ export const AUTOMATED_PROPOSAL_SOURCES = [
     "consolidate",
     "extract",
     "improve",
+    "recombine",
+    "procedural",
     "schema-repair",
 ];
 /**
@@ -334,37 +339,42 @@ export function createProposal(stashDir, input, ctx) {
     }
     const normalizedRef = makeAssetRef(parsedRef.type, parsedRef.name, parsedRef.origin);
     return withProposalsDb(stashDir, ctx, (db) => {
-        if (!input.force) {
-            const skip = checkDedupAndCooldown(db, stashDir, normalizedRef, input, ctx);
-            if (skip)
-                return skip;
-        }
-        const created = nowIso(ctx);
-        // Phase 6A: validate confidence is a finite number in [0, 1]. Anything else
-        // is dropped silently — we never store NaN, Infinity, or out-of-range values.
-        // Callers that mis-report confidence should not poison the auto-accept gate.
-        const sanitizedConfidence = typeof input.confidence === "number" &&
-            Number.isFinite(input.confidence) &&
-            input.confidence >= 0 &&
-            input.confidence <= 1
-            ? input.confidence
-            : undefined;
-        const proposal = {
-            id: newId(ctx),
-            ref: normalizedRef,
-            status: "pending",
-            source: input.source,
-            ...(input.sourceRun !== undefined ? { sourceRun: input.sourceRun } : {}),
-            createdAt: created,
-            updatedAt: created,
-            payload: {
-                content: input.payload.content,
-                ...(input.payload.frontmatter !== undefined ? { frontmatter: input.payload.frontmatter } : {}),
-            },
-            ...(sanitizedConfidence !== undefined ? { confidence: sanitizedConfidence } : {}),
-        };
-        upsertProposal(db, proposal, stashDir);
-        return proposal;
+        return withImmediateTransaction(db, () => {
+            if (!input.force) {
+                const skip = checkDedupAndCooldown(db, stashDir, normalizedRef, input, ctx);
+                if (skip)
+                    return skip;
+            }
+            const created = nowIso(ctx);
+            // Phase 6A: validate confidence is a finite number in [0, 1]. Anything else
+            // is dropped silently — we never store NaN, Infinity, or out-of-range values.
+            // Callers that mis-report confidence should not poison the auto-accept gate.
+            const sanitizedConfidence = typeof input.confidence === "number" &&
+                Number.isFinite(input.confidence) &&
+                input.confidence >= 0 &&
+                input.confidence <= 1
+                ? input.confidence
+                : undefined;
+            const proposal = {
+                id: newId(ctx),
+                ref: normalizedRef,
+                status: "pending",
+                source: input.source,
+                ...(input.sourceRun !== undefined ? { sourceRun: input.sourceRun } : {}),
+                createdAt: created,
+                updatedAt: created,
+                payload: {
+                    content: input.payload.content,
+                    ...(input.payload.frontmatter !== undefined ? { frontmatter: input.payload.frontmatter } : {}),
+                },
+                ...(sanitizedConfidence !== undefined ? { confidence: sanitizedConfidence } : {}),
+                // Attribution tagging: persist the eligibility lane so it survives to
+                // accept/reject/revert time. See EligibilitySource.
+                ...(input.eligibilitySource !== undefined ? { eligibilitySource: input.eligibilitySource } : {}),
+            };
+            upsertProposal(db, proposal, stashDir);
+            return proposal;
+        });
     });
 }
 /**
@@ -517,19 +527,25 @@ export function resolveProposalId(stashDir, idOrRef, ctx) {
  */
 export function archiveProposal(stashDir, id, status, reason, ctx) {
     return withProposalsDb(stashDir, ctx, (db) => {
-        const existing = requireProposal(db, stashDir, id);
-        const updated = {
-            ...existing,
-            status,
-            updatedAt: nowIso(ctx),
-            review: {
-                outcome: status,
-                ...(reason !== undefined ? { reason } : {}),
-                decidedAt: nowIso(ctx),
-            },
-        };
-        upsertProposal(db, updated, stashDir);
-        return updated;
+        return withImmediateTransaction(db, () => {
+            const existing = requireProposal(db, stashDir, id);
+            if (existing.status !== "pending") {
+                throw new UsageError(`Proposal ${id} is not pending (current status: ${existing.status}). Only pending proposals can be ${status}.`, "INVALID_FLAG_VALUE");
+            }
+            const decidedAt = nowIso(ctx);
+            const updated = {
+                ...existing,
+                status,
+                updatedAt: decidedAt,
+                review: {
+                    outcome: status,
+                    ...(reason !== undefined ? { reason } : {}),
+                    decidedAt,
+                },
+            };
+            upsertProposal(db, updated, stashDir);
+            return updated;
+        });
     });
 }
 /**
@@ -548,15 +564,17 @@ export function archiveProposal(stashDir, id, status, reason, ctx) {
  */
 export function recordGateDecision(stashDir, id, decision, ctx) {
     return withProposalsDb(stashDir, ctx, (db) => {
-        const existing = getStateProposal(db, id, stashDir);
-        if (!existing)
-            return undefined;
-        const updated = {
-            ...existing,
-            gateDecision: { ...decision, decidedAt: decision.decidedAt ?? nowIso(ctx) },
-        };
-        upsertProposal(db, updated, stashDir);
-        return updated;
+        return withImmediateTransaction(db, () => {
+            const existing = getStateProposal(db, id, stashDir);
+            if (!existing || existing.status !== "pending")
+                return undefined;
+            const updated = {
+                ...existing,
+                gateDecision: { ...decision, decidedAt: decision.decidedAt ?? nowIso(ctx) },
+            };
+            upsertProposal(db, updated, stashDir);
+            return updated;
+        });
     });
 }
 /**
@@ -699,6 +717,99 @@ export function expireStaleProposals(stashDir, config, ctx) {
 export function validateProposal(proposal) {
     return runProposalValidators(proposal);
 }
+// ── Content repair ──────────────────────────────────────────────────────────
+/**
+ * Attempt bounded, deterministic repair of mechanically-fixable defects in a
+ * proposal's markdown content. NEVER fabricates text — only strips known-bad
+ * 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
+ *      `description` field in the frontmatter.
+ *
+ * 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.
+ *
+ * CRITICAL: This function is CONTENT-PRESERVING. Callers MUST re-validate the
+ * repaired output via {@link validateProposal} / {@link runProposalValidators}
+ * before promotion — a repair that makes things *worse* (or is simply
+ * insufficient) must be caught by the existing gate.
+ */
+export function repairProposalContent(content) {
+    if (typeof content !== "string" || content.trim() === "")
+        return content;
+    // Determine whether the content has a frontmatter block so we know how
+    // many `---` fence lines are expected.
+    const hasFrontmatter = /^---\r?\n[\s\S]*?\r?\n---/.test(content);
+    // Split into lines for structural repairs.
+    const lines = content.split(/\r?\n/);
+    // Track whether we are inside the opening frontmatter block so we can
+    // leave it untouched and only repair the body.
+    let inFrontmatter = false;
+    // Frontmatter fence index tracking: first fence opens FM, second closes it.
+    let fmOpenSeen = false;
+    let fmCloseSeen = false;
+    const repairedLines = [];
+    for (const line of lines) {
+        const isFence = /^---\s*$/.test(line);
+        // Track frontmatter fences (first two `---` fences delimit the FM block).
+        if (isFence && !fmCloseSeen) {
+            if (!fmOpenSeen) {
+                fmOpenSeen = true;
+                inFrontmatter = true;
+                repairedLines.push(line);
+                continue;
+            }
+            if (inFrontmatter) {
+                fmCloseSeen = true;
+                inFrontmatter = false;
+                repairedLines.push(line);
+                continue;
+            }
+        }
+        // We are now in the body (past the frontmatter or no frontmatter).
+        if (inFrontmatter) {
+            // Still inside the frontmatter — keep as-is.
+            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");
+    // Repair 3: Apply repairTruncatedDescription to the description field.
+    // We operate on the raw text rather than re-parsing YAML to avoid
+    // reformatting unrelated frontmatter keys.
+    if (hasFrontmatter) {
+        // Extract the body text (after the second `---`) so we can pass it to
+        // repairTruncatedDescription as context for the swap-in heuristic.
+        const bodyMatch = repaired.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
+        const bodyText = bodyMatch?.[1] ?? "";
+        repaired = repaired.replace(/^(description:\s*)(.*?)(\r?\n)/m, (_match, prefix, rawDesc, nl) => {
+            const fixed = repairTruncatedDescription(rawDesc.trim(), bodyText);
+            return `${prefix}${fixed}${nl}`;
+        });
+    }
+    return repaired;
+}
 /**
  * Validate a proposal, then promote it through the canonical
  * {@link writeAssetToSource} dispatch (the single place that branches on
@@ -716,12 +827,31 @@ export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
     if (proposal.status !== "pending") {
         throw new UsageError(`Proposal ${id} is not pending (current status: ${proposal.status}). Only pending proposals can be accepted.`, "INVALID_FLAG_VALUE");
     }
-    const report = validateProposal(proposal);
+    // Attempt bounded auto-repair of mechanically-fixable structural defects
+    // (pseudo-frontmatter-in-body, stray `---` fences, truncated description)
+    // BEFORE running validation. If the repair produces valid content, we
+    // promote the repaired version; if validation still fails, the original
+    // error path throws as before. The repair is content-preserving and
+    // deterministic — it never invents text.
+    const repairedContent = repairProposalContent(proposal.payload.content);
+    const proposalToValidate = repairedContent !== proposal.payload.content
+        ? { ...proposal, payload: { ...proposal.payload, content: repairedContent } }
+        : proposal;
+    const report = validateProposal(proposalToValidate);
     if (!report.ok) {
         const message = report.findings.map((f) => `[${f.kind}] ${f.message}`).join("\n");
         throw new UsageError(`Proposal ${id} failed validation:\n${message}`, "MISSING_REQUIRED_ARGUMENT", "Fix the proposal payload (frontmatter / content) and try again, or reject the proposal with a reason.");
     }
-    const ref = parseAssetRef(proposal.ref);
+    // Use the (possibly repaired) payload for the promotion write. Persist the
+    // repaired content back onto the DB row so the audit trail reflects the
+    // final promoted payload (not the defective original).
+    if (repairedContent !== proposal.payload.content) {
+        withProposalsDb(stashDir, ctx, (db) => {
+            const updated = { ...proposal, payload: { ...proposal.payload, content: repairedContent } };
+            upsertProposal(db, updated, stashDir);
+        });
+    }
+    const ref = parseAssetRef(proposalToValidate.ref);
     if (!TYPE_DIRS[ref.type]) {
         throw new UsageError(`Proposal ${id} targets unknown asset type "${ref.type}".`, "INVALID_FLAG_VALUE");
     }
@@ -743,7 +873,7 @@ export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
         // missing-revert path is visible.
         warn(`[proposals] promoteProposal: failed to capture backup for ${id}: ${err instanceof Error ? err.message : String(err)}`);
     }
-    const written = await writeAssetToSource(target.source, target.config, ref, proposal.payload.content);
+    const written = await writeAssetToSource(target.source, target.config, ref, repairedContent);
     // 0.9.0 (issue #507): single batch commit at the write boundary for git
     // targets. No-op for filesystem/primary-stash targets.
     commitWriteTargetBoundary(target, `Update ${formatRefForMessage(ref)}`);