akm-cli 0.9.0-beta.35 → 0.9.0-beta.36

package/CHANGELOG.md

@@ -6,6 +6,41 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.0-beta.36] — 2026-06-22
+
+### Added
+
+- **Stash standards + wiki schemas are surfaced to authoring agents at write
+  time.** When an agent edits a page under `wikis/<name>/`, that wiki's
+  `schema.md` body is injected into the prompt; when it creates/edits a non-wiki
+  asset, the bodies of `category: convention`/`meta` `fact` assets are injected.
+  Two mutually-exclusive features selected by target type, sharing one
+  `standardsContext` prompt seam. Wired into reflect, propose, and every
+  improve authoring pass (distill, consolidate, recombine, procedural, extract,
+  schema-repair). (#642)
+- **Unified, validator-sourced authoring-rules seam.** A new
+  `authoringRulesForType(type)` injects the hard authoring rules (no
+  pseudo-frontmatter in body, exactly two `---` fences, description/`when_to_use`
+  length + shape) into every authoring prompt. The numeric bounds live in one
+  module that the validators import, so the prompt can no longer drift from what
+  the gate enforces. (#645)
+
+### Fixed
+
+- **High-salience reflect lane now reflects each asset at most once.** The
+  `#608` admission gate lacked the cooldown its sibling high-retrieval gate has,
+  so zero-feedback assets were re-selected on every run (auto-accept emits
+  `promoted`, not `feedback`), burning LLM calls and churning assets. (#643)
+- **Stuck validation-failing proposals no longer dead-end.** The triage drain no
+  longer overwrites an `auto-rejected` gate stamp with a misleading
+  `auto-accepted` (the failure stays truthful and visible). A bounded,
+  content-preserving auto-repair (strip pseudo-frontmatter / stray `---`, repair
+  truncated descriptions) runs at the promote boundary and re-validates — fixable
+  proposals promote; genuinely unrepairable ones stay `pending` for manual
+  review, with nothing fabricated and validation never bypassed. (#645)
+- Corrected a prompt/validator drift where the distill system prompt asked for an
+  80–200 char description while the gate enforced 20–400. (#645)
+
 ## [0.9.0-beta.35] — 2026-06-21
 
 ### Fixed

package/dist/assets/prompts/distill-lesson-system.md

@@ -15,7 +15,7 @@ when_to_use: <one complete sentence describing the concrete trigger condition>
 <lesson body — plain markdown, 1–3 short paragraphs of practical guidance>
 
 ## description field (MANDATORY)
-- A single complete sentence in present tense, 80-200 chars, NO markdown.
+- A single complete sentence in present tense, 20–400 chars, NO markdown.
 - Self-contained: a reviewer must understand the lesson from this field alone.
 - DO NOT start with "When ", "If ", or a connector word — that belongs in when_to_use.
 - DO NOT copy a section heading ("Key takeaways", "For example", "Key pitfalls").

package/dist/assets/prompts/extract-session.md

@@ -28,7 +28,7 @@ Things NOT to extract:
 - Started: {{STARTED_AT}}
 - Ended: {{ENDED_AT}}
 - Project hint: {{PROJECT_HINT}}
-
+{{STANDARDS}}
 ## Filtered session transcript
 
 The transcript below has already had read-only `akm` meta-ops and platform boilerplate stripped. Only content that might carry signal remains.

package/dist/commands/improve/consolidate.js

@@ -15,6 +15,7 @@ import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
 // Note: appendEvent import removed (WS-3a: archive TTL machinery retired)
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { detectTruncatedDescription } from "../../core/text-truncation.js";
 import { hasHotCaptureMode, hasSupersededStatus, MERGE_ABSOLUTE_FLOOR_CHARS, MERGE_SHRINK_RATIO_MIN, validateProposalFrontmatter, } from "../proposal/validators/proposal-quality-validators.js";
 import { createProposal, isProposalSkipped, listProposals } from "../proposal/validators/proposals.js";
@@ -377,7 +378,7 @@ async function clusterMemoriesBySimilarity(memories, config, stateDb) {
  * is precomputed once per run by `loadPendingConsolidateProposalHashes`
  * so the cost stays O(memories) inside the chunk loop.
  */
-export function buildChunkPrompt(sourceName, memories, chunkIndex, totalChunks, bodyTruncation, pendingProposalBodyHashes = new Set()) {
+export function buildChunkPrompt(sourceName, memories, chunkIndex, totalChunks, bodyTruncation, pendingProposalBodyHashes = new Set(), standardsContext = "") {
     const start = memories[0] ? `memory:${memories[0].name}` : "";
     const end = memories[memories.length - 1] ? `memory:${memories[memories.length - 1].name}` : "";
     const annotationsByIndex = [];
@@ -405,6 +406,11 @@ export function buildChunkPrompt(sourceName, memories, chunkIndex, totalChunks,
         `Chunk ${chunkIndex + 1} of ${totalChunks}, memories ${start}–${end}:`,
         "",
     ];
+    if (standardsContext.trim()) {
+        lines.push("Standards to follow (the rulebook for this target):");
+        lines.push(standardsContext.trim());
+        lines.push("");
+    }
     // Top-of-prompt protection block for hot refs. Neutral phrasing — avoid
     // op-words like "promote", "merge", "contradict" so the model doesn't
     // accidentally treat the warning as a hint to use that op elsewhere
@@ -1246,6 +1252,10 @@ async function akmConsolidateInner(opts, config, stashDir, startMs, sourceRun, w
     }
     warn(`[consolidate] ${memories.length} memories / ${chunks.length} chunk(s) / chunk_size=${chunkSize}` +
         ` / pending-proposal hashes: ${pendingProposalBodyHashes.size}`);
+    // Consolidate output merges memories (non-wiki) → stash authoring standards.
+    // Resolved ONCE per run and passed to each chunk prompt (facts not re-read
+    // per chunk).
+    const standardsContext = resolveStashStandards(stashDir);
     const chunkOpsArrays = [];
     // Structured skip-reason histogram (2026-05-26): every deterministic
     // post-LLM op rejection site below also calls `pushSkipReason` so the
@@ -1363,7 +1373,7 @@ async function akmConsolidateInner(opts, config, stashDir, startMs, sourceRun, w
             continue;
         }
         warn(`[consolidate] chunk ${chunkIdx + 1}/${chunks.length} (${chunk.length} memories) …`);
-        const userPrompt = buildChunkPrompt(sourceName, chunk, chunkIdx, chunks.length, bodyTruncation, pendingProposalBodyHashes);
+        const userPrompt = buildChunkPrompt(sourceName, chunk, chunkIdx, chunks.length, bodyTruncation, pendingProposalBodyHashes, standardsContext);
         let raw = await tryLlmFeature("memory_consolidation", config, async () => {
             if (!llmConfig)
                 return { ok: false, error: "No LLM configured for consolidation" };

package/dist/commands/improve/distill.js

@@ -58,12 +58,14 @@ import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { assembleAssetFromString } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter, writeSalienceToFrontmatter } from "../../core/asset/frontmatter.js";
 import { stripMarkdownFences } from "../../core/asset/markdown.js";
+import { authoringRulesForType } from "../../core/authoring-rules.js";
 import { resolveStashDir, timestampForFilename } from "../../core/common.js";
 import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { lintLessonContent } from "../../core/lesson-lint.js";
 import { getDbPath } from "../../core/paths.js";
+import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { openStateDatabase } from "../../core/state-db.js";
 import { warnVerbose } from "../../core/warn.js";
 import { closeDatabase, getAllEntries, openDatabase } from "../../indexer/db/db.js";
@@ -307,6 +309,18 @@ export function buildDistillPrompt(input) {
     const lines = [];
     lines.push(`Asset ref: ${input.inputRef}`);
     lines.push("");
+    if (input.standardsContext?.trim()) {
+        lines.push("Standards to follow (the rulebook for this target):");
+        lines.push(input.standardsContext.trim());
+        lines.push("");
+    }
+    {
+        const authoringRules = authoringRulesForType(input.proposalKind ?? "lesson");
+        if (authoringRules) {
+            lines.push(authoringRules);
+            lines.push("");
+        }
+    }
     lines.push("Asset content:");
     if (input.assetContent) {
         const body = input.assetContent.trim().slice(0, 3000);
@@ -939,12 +953,16 @@ export async function akmDistill(options) {
             // Fail open — CLS is supplemental, never required.
         }
     }
+    // Distill output is a lesson/knowledge (non-wiki) → stash authoring
+    // standards. Resolved once for this single call.
+    const standardsContext = resolveStashStandards(stash);
     const baseUserPrompt = buildDistillPrompt({
         inputRef,
         assetContent,
         feedback,
         proposalKind: effectiveProposalKind,
         ...(rejectedForRef.length > 0 ? { rejectedProposals: rejectedForRef } : {}),
+        ...(standardsContext.trim() ? { standardsContext } : {}),
     });
     const userPrompt = clsContext ? `${baseUserPrompt}${clsContext}` : baseUserPrompt;
     const messages = [

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

@@ -149,6 +149,11 @@ export function buildExtractPrompt(input) {
     const ref = input.data.ref;
     const startedAt = ref.startedAt ? new Date(ref.startedAt).toISOString() : "unknown";
     const endedAt = ref.endedAt ? new Date(ref.endedAt).toISOString() : "unknown";
+    // Optional standards block — rendered to the lead-in + body when present,
+    // or an empty string (no section) when absent. Gated on non-empty.
+    const standards = input.standardsContext?.trim()
+        ? `\n## Standards to follow (the rulebook for this target)\n\n${input.standardsContext.trim()}\n`
+        : "";
     return promptTemplate
         .replace("{{HARNESS}}", ref.harness)
         .replace("{{TITLE}}", ref.title ?? "(no title)")
@@ -156,6 +161,7 @@ export function buildExtractPrompt(input) {
         .replace("{{ENDED_AT}}", endedAt)
         .replace("{{PROJECT_HINT}}", ref.projectHint ?? "(no project hint)")
         .replace("{{ALREADY_PRESERVED}}", formatAlreadyPreserved(input.inlineRefs))
+        .replace("{{STANDARDS}}", standards)
         .replace("{{TRANSCRIPT}}", formatTranscript(input.events));
 }
 /**

package/dist/commands/improve/extract.js

@@ -31,6 +31,7 @@ import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { probeLock, releaseLock, tryAcquireLockSync } from "../../core/file-lock.js";
+import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { getExtractedSessionsMap, getLastExtractRunAt, getStateDbPath, openStateDatabase, shouldSkipAlreadyExtractedSession, upsertExtractedSession, } from "../../core/state-db.js";
 import { repairTruncatedDescription } from "../../core/text-truncation.js";
 import { warn } from "../../core/warn.js";
@@ -265,7 +266,11 @@ triage, sessionIndexing, schemaSimilarityCtx,
 // prior row + bypass flags are threaded in from the caller. Skipping here still
 // costs ZERO LLM calls (the expensive resource #602 protects); only the cheap
 // file read is incurred.
-prior, force) {
+prior, force, 
+// Stash authoring standards (convention/meta fact bodies) for non-wiki
+// output. Resolved ONCE per run by the caller and threaded in so facts are
+// not re-read per session. Empty string when none exist.
+standardsContext) {
     const warnings = [];
     let data;
     try {
@@ -360,7 +365,12 @@ prior, force) {
             };
         }
     }
-    const prompt = buildExtractPrompt({ data, events: filtered.events, inlineRefs: data.inlineRefs });
+    const prompt = buildExtractPrompt({
+        data,
+        events: filtered.events,
+        inlineRefs: data.inlineRefs,
+        ...(standardsContext.trim() ? { standardsContext } : {}),
+    });
     // #561 — ADDITIVE session indexing. Generate + write the session asset
     // (`sessions/<harness>/<id>.md`). FAIL-OPEN: any failure only records a
     // warning; it NEVER changes the proposal/skip outcome of extract. Returns the
@@ -771,6 +781,10 @@ export async function akmExtract(options) {
             embedFn: options.schemaSimilarityEmbedFn,
         };
     }
+    // Stash authoring standards (convention/meta fact bodies) for non-wiki
+    // extract output. Resolved ONCE per run and threaded into each session's
+    // prompt so facts are not re-read per session.
+    const extractStandardsContext = resolveStashStandards(stashDir);
     for (const summary of candidates) {
         // #602 — the already-extracted skip moved INTO processSession (the content
         // hash needs the session body, only available after readSession). The prior
@@ -810,7 +824,7 @@ export async function akmExtract(options) {
             }
         }
         try {
-            const result = await processSession(harness, summary, stashDir, config, llmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, triage, sessionIndexing, schemaSimilarityCtx, prior, options.force === true);
+            const result = await processSession(harness, summary, stashDir, config, llmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, triage, sessionIndexing, schemaSimilarityCtx, prior, options.force === true, extractStandardsContext);
             sessions.push(result);
             // #626 — triage aggregation. A session reached the triage gate only when it
             // was NOT already preempted by an earlier skip (read_failed / too_short /

package/dist/commands/improve/improve.js

@@ -2463,6 +2463,14 @@ async function runImprovePreparationStage(args) {
     // Cap: at most 10% of the effective run limit so the lane cannot crowd out
     // reactive feedback. Requires state.db to have an asset_salience row — refs
     // without a row (pre-#608 assets still on the type-weight stub) are skipped.
+    //
+    // Cooldown: a ref qualifies at most once — when no prior reflect proposal
+    // exists for it (`!lastReflectProposalTs.has`). Without this guard the lane
+    // re-selects the same high-salience refs on EVERY run (auto-accept emits a
+    // `promoted` event, not `feedback`, so the ref never leaves
+    // noFeedbackCandidates), burning LLM calls and churning the asset. This
+    // mirrors the P0-A high-retrieval gate's `!lastReflectProposalTs.has(r.ref)`
+    // guard above so all "rescue" lanes share the same once-per-asset semantics.
     const highSalienceRefs = [];
     const salienceCfg = (options.config ?? loadConfig()).improve?.salience;
     const salienceThreshold = salienceCfg?.salienceThreshold ?? 0.75;
@@ -2478,7 +2486,7 @@ async function runImprovePreparationStage(args) {
                 if (highSalienceRefs.length >= highSalienceCap)
                     break;
                 const row = getAssetSalience(dbForHighSalience, r.ref);
-                if (row && row.encoding_salience >= salienceThreshold) {
+                if (row && row.encoding_salience >= salienceThreshold && !lastReflectProposalTs.has(r.ref)) {
                     highSalienceRefs.push(r);
                 }
             }

package/dist/commands/improve/procedural.js

@@ -27,6 +27,7 @@ import { resolveStashDir } from "../../core/common.js";
 import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
 import { appendEvent } from "../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { warn } from "../../core/warn.js";
 import { closeDatabase, getAllEntries, openExistingDatabase } from "../../indexer/db/db.js";
 import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
@@ -144,12 +145,17 @@ export function deriveProceduralWorkflowRef(cluster) {
 }
 // ── Prompt + parse ──────────────────────────────────────────────────────────────
 /** Assemble the per-sequence user prompt fed to the procedural LLM. */
-export function buildProceduralPrompt(cluster) {
+export function buildProceduralPrompt(cluster, standardsContext = "") {
     const lines = [
         `A recurring successful action sequence observed across ${cluster.members.length} sessions.`,
         "",
-        "Ordered actions (turn EACH into exactly one step, in this order):",
     ];
+    if (standardsContext.trim()) {
+        lines.push("Standards to follow (the rulebook for this target):");
+        lines.push(standardsContext.trim());
+        lines.push("");
+    }
+    lines.push("Ordered actions (turn EACH into exactly one step, in this order):");
     cluster.normalized.forEach((step, i) => {
         lines.push(`${i + 1}. ${step}`);
     });
@@ -312,6 +318,9 @@ export async function akmProcedural(opts) {
         warnings.push("procedural: no LLM configured — skipping");
         return finish({ sequencesScanned, clustersFormed: 0 });
     }
+    // Procedural output is a workflow (non-wiki) → stash authoring standards.
+    // Resolved ONCE per run and passed to each sequence prompt.
+    const standardsContext = resolveStashStandards(stashDir);
     for (const cluster of clusters) {
         if (opts.signal?.aborted) {
             warnings.push("aborted-mid-run");
@@ -319,7 +328,7 @@ export async function akmProcedural(opts) {
         }
         clustersFormed += 1;
         const workflowRef = deriveProceduralWorkflowRef(cluster);
-        const prompt = buildProceduralPrompt(cluster);
+        const prompt = buildProceduralPrompt(cluster, standardsContext);
         const raw = await llmFn(prompt);
         const doc = parseProceduralWorkflow(raw, cluster.normalized.length);
         if (!doc) {

package/dist/commands/improve/recombine.js

@@ -45,6 +45,7 @@ import { resolveStashDir } from "../../core/common.js";
 import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
 import { appendEvent } from "../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { decayUnseenRecombineHypotheses, findMatchingRecombineHypothesis, getRecombineHypothesis, getStateDbPath, markRecombineHypothesisPromoted, openStateDatabase, recordRecombineInduction, } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
 import { closeDatabase, getAllEntries, getEntitiesByEntryIds, openExistingDatabase, } from "../../indexer/db/db.js";
@@ -228,12 +229,17 @@ function readBody(entry) {
     }
 }
 /** Assemble the per-cluster user prompt fed to the recombine LLM. */
-export function buildClusterPrompt(cluster) {
+export function buildClusterPrompt(cluster, standardsContext = "") {
     const lines = [
         `Shared signal: ${cluster.signature}`,
         `Cluster of ${cluster.members.length} related memories:`,
         "",
     ];
+    if (standardsContext.trim()) {
+        lines.push("Standards to follow (the rulebook for this target):");
+        lines.push(standardsContext.trim());
+        lines.push("");
+    }
     for (const m of cluster.members) {
         lines.push(`[memory:${m.entry.name}]`);
         if (m.entry.description)
@@ -399,6 +405,9 @@ export async function akmRecombine(opts) {
     // Refs re-induced (defensible generalization passed the quality gate) THIS
     // run — everything else is decayed after the loop.
     const seenThisRun = new Set();
+    // Recombine output is knowledge/lesson (non-wiki) → stash authoring
+    // standards. Resolved ONCE per run and passed to each cluster prompt.
+    const standardsContext = resolveStashStandards(stashDir);
     try {
         for (const cluster of clusters) {
             if (opts.signal?.aborted) {
@@ -406,7 +415,7 @@ export async function akmRecombine(opts) {
                 break;
             }
             clustersFormed += 1;
-            const prompt = buildClusterPrompt(cluster);
+            const prompt = buildClusterPrompt(cluster, standardsContext);
             const raw = await llmFn(prompt);
             const generalization = parseGeneralization(raw);
             if (!generalization) {

package/dist/commands/improve/reflect.js

@@ -34,6 +34,7 @@ import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { lintLessonContent } from "../../core/lesson-lint.js";
+import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { lookup } from "../../indexer/indexer.js";
 import { runAgent, } from "../../integrations/agent/index.js";
 import { resolveProcessAgentProfile } from "../../integrations/agent/config.js";
@@ -745,6 +746,9 @@ export async function akmReflect(options = {}) {
     // Reflexion-style verbal-RL: inject rejected proposals so the agent avoids
     // reproducing proposals that have already been reviewed and refused.
     const rejectedProposals = readRejectedProposals(stash, options.ref);
+    // 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.ref, stash);
     // 5. Spawn the agent — with optional Self-Refine loop (R-1 / #372).
     //
     // maxRefineIters controls how many agent invocations are made:
@@ -813,6 +817,7 @@ export async function akmReflect(options = {}) {
                 ...(schemaHints.length > 0 ? { schemaHints } : {}),
                 ...(relatedLessons.length > 0 ? { relatedLessons } : {}),
                 ...(options.task ? { task: options.task } : {}),
+                ...(standardsContext.trim() ? { standardsContext } : {}),
                 ...(options.avoidPatterns && options.avoidPatterns.length > 0 ? { avoidPatterns: options.avoidPatterns } : {}),
                 ...(rejectedProposals.length > 0 ? { rejectedProposals } : {}),
                 // R-1: inject prior draft as self-critique target on iterations > 0

package/dist/commands/proposal/drain.js

@@ -370,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/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

@@ -51,6 +51,7 @@ import { resolveAssetPathFromName, TYPE_DIRS } from "../../../core/asset/asset-s
 import { NotFoundError, UsageError } from "../../../core/errors.js";
 import { appendEvent } from "../../../core/events.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";
@@ -716,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
@@ -733,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");
     }
@@ -760,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)}`);

package/dist/commands/sources/schema-repair.js

@@ -17,7 +17,9 @@ import path from "node:path";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { authoringRulesForType } from "../../core/authoring-rules.js";
 import { appendEvent, readEvents } from "../../core/events.js";
+import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { info, warn } from "../../core/warn.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { chatCompletion, parseEmbeddedJsonResponse } from "../../llm/client.js";
@@ -94,6 +96,16 @@ export async function runSchemaRepairPass(failures, options) {
             const fieldList = missingFields.join(" and ");
             info(`[improve] schema-repair ${failure.ref} (${fieldList})`);
             const bodyPreview = (fm.content ?? raw).slice(0, 2000);
+            // Standards "rulebook" for this target — wiki schema (wiki page) or stash
+            // convention/meta facts (non-wiki asset); empty when neither fires or no
+            // stash dir is available. `resolveStandardsContext` dispatches on the ref.
+            const standardsContext = stashDir ? resolveStandardsContext(failure.ref, stashDir) : "";
+            const standardsSection = standardsContext.trim()
+                ? `\n\nStandards to follow (the rulebook for this target):\n${standardsContext.trim()}`
+                : "";
+            const assetType = parseAssetRef(failure.ref).type;
+            const authoringRules = authoringRulesForType(assetType);
+            const authoringRulesSection = authoringRules ? `\n\n${authoringRules}` : "";
             const llmResponse = await chatFn(llmConfig, [
                 {
                     role: "system",
@@ -101,7 +113,7 @@ export async function runSchemaRepairPass(failures, options) {
                 },
                 {
                     role: "user",
-                    content: `Generate the missing frontmatter fields (${fieldList}) for this ${parseAssetRef(failure.ref).type} asset. Return ONLY valid JSON like {"description": "...", "when_to_use": "..."}\n\n${bodyPreview}`,
+                    content: `Generate the missing frontmatter fields (${fieldList}) for this ${assetType} asset. Return ONLY valid JSON like {"description": "...", "when_to_use": "..."}${standardsSection}${authoringRulesSection}\n\n${bodyPreview}`,
                 },
             ]);
             const parsed = parseEmbeddedJsonResponse(llmResponse.trim());

package/dist/core/authoring-rules.js

@@ -0,0 +1,83 @@
+// 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/.
+/**
+ * Canonical HARD authoring rules — the single source of truth shared by the
+ * proposal validators (which REJECT violations) and the improve/authoring
+ * prompts (which must TELL the agent the same rules, in the same words).
+ *
+ * Why this module exists: authoring rules were duplicated and drifted across
+ * prompt templates. `distill-lesson-system.md` told the model "80–200 chars"
+ * while the validator enforced 20–400; reflect's prompt omitted the
+ * no-pseudo-frontmatter / single-fence rules entirely, so reflect generated
+ * proposals that the gate then rejected and that got stuck in the queue.
+ *
+ * The fix: the numeric bounds live HERE and are imported by both the validators
+ * (`isValidDescription` / `isValidWhenToUse` in proposal-quality-validators.ts)
+ * and the prompt text (`authoringRulesForType`). The agent-facing rule prose
+ * sits next to the bounds it describes, so a developer changing a validator
+ * sees the prompt copy that must change with it. `tests/authoring-rules-*`
+ * asserts the two representations stay consistent.
+ *
+ * SCOPE: only HARD rules (a validator rejects the proposal if violated) belong
+ * here. Soft/style conventions (voice, paragraph count, "include a # Title")
+ * are user-editable and flow through the separate `standardsContext` seam
+ * (stash `category: convention` facts) — NOT this module.
+ */
+// ── Canonical numeric bounds (imported by the validators — do not duplicate) ──
+/** `description` length bounds (chars). Enforced by `isValidDescription`. */
+export const DESCRIPTION_MIN_CHARS = 20;
+export const DESCRIPTION_MAX_CHARS = 400;
+/** `when_to_use` length bounds (chars). Enforced by `isValidWhenToUse`. */
+export const WHEN_TO_USE_MIN_CHARS = 15;
+export const WHEN_TO_USE_MAX_CHARS = 400;
+// ── Agent-facing rule prose (mirrors the validator checks one-for-one) ────────
+/**
+ * Rules that apply to any markdown asset authored with YAML frontmatter + a
+ * body. Enforced by `detectDoubleFrontmatter` (currently fires for lesson
+ * proposals, but the rules are universally correct, so we state them for every
+ * type to prevent the same defect class elsewhere).
+ */
+const FRONTMATTER_BODY_RULES = [
+    "Emit EXACTLY TWO `---` fence lines — the opening and closing of the YAML frontmatter. Do NOT use `---` as a horizontal rule anywhere in the body.",
+    "Do NOT restate `description:` or `when_to_use:` inside the body (no `**description:** …` or `**when_to_use:** …` lines). Those keys belong in the frontmatter ONLY.",
+];
+/** Rules for the `description` frontmatter field. Enforced by `isValidDescription`. */
+const DESCRIPTION_RULES = [
+    `\`description\` must be ${DESCRIPTION_MIN_CHARS}–${DESCRIPTION_MAX_CHARS} characters of plain-prose sentence — no leading digit or markdown marker, balanced backticks, and it must NOT end with \`:\`, \`;\`, or \`,\` (those read as truncation).`,
+    '`description` must NOT be a section-heading fragment (e.g. "Overview", "Key points", "Summary"), a code fragment (must not start with `def`/`function`/`class`/`const`/…), or end on a hanging connector word ("a", "the", "and", "to", …).',
+    "`description` must NOT merely restate the asset's ref/name; write what the asset actually does.",
+    '`description` should NOT start with "When" — that phrasing belongs in `when_to_use`.',
+];
+/** Rules for the `when_to_use` frontmatter field. Enforced by `isValidWhenToUse`. */
+const WHEN_TO_USE_RULES = [
+    `\`when_to_use\` is REQUIRED and must be ${WHEN_TO_USE_MIN_CHARS}–${WHEN_TO_USE_MAX_CHARS} characters describing a concrete trigger. Never write the circular fallback "When working with <name>".`,
+    "`description` and `when_to_use` must be different from each other.",
+];
+/**
+ * Asset types that carry a `description` and a body where the
+ * frontmatter/body rules apply. (Types without those — if any are added later —
+ * simply fall through to the cross-cutting block.)
+ */
+const DESCRIPTION_TYPES = new Set(["lesson", "knowledge", "memory", "skill", "command", "agent", "workflow", "fact"]);
+/** Types where `when_to_use` is a HARD requirement (validator rejects if absent). */
+const WHEN_TO_USE_TYPES = new Set(["lesson"]);
+/**
+ * Build the hard-rules block for a given asset type, ready to inject as a prompt
+ * section. Returns `""` for an unknown type (no over-claiming). The block is
+ * deterministic so prompt snapshots stay stable.
+ *
+ * Inject this VERBATIM into every improve/authoring prompt that creates or edits
+ * an asset of `type`, so the agent is told exactly what the gate will reject.
+ */
+export function authoringRulesForType(type) {
+    const rules = [...FRONTMATTER_BODY_RULES];
+    if (DESCRIPTION_TYPES.has(type))
+        rules.push(...DESCRIPTION_RULES);
+    if (WHEN_TO_USE_TYPES.has(type))
+        rules.push(...WHEN_TO_USE_RULES);
+    if (rules.length === 0)
+        return "";
+    const heading = `Hard authoring rules for ${type} assets (the validator REJECTS proposals that violate these):`;
+    return [heading, ...rules.map((r) => `- ${r}`)].join("\n");
+}

package/dist/core/standards/resolve-standards-context.js

@@ -0,0 +1,56 @@
+// 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/.
+/**
+ * Dispatch resolver for the standards prompt seam — selects which of the two
+ * standards features fires for a given write target, mutually exclusively:
+ *
+ *   - **Feature A — wiki schema**: the target is a wiki page (a ref/path under
+ *     `wikis/<name>/`, NOT a `raw/` file and NOT a wiki infra file
+ *     `schema.md`/`index.md`/`log.md`). Returns that wiki's `schema.md` body.
+ *   - **Feature B — stash standards**: the target is any non-wiki asset.
+ *     Returns the concatenated `category: convention`/`meta` fact bodies.
+ *   - **Neither fires**: a wiki `raw/` file or a wiki infra file. Returns `""`.
+ *
+ * The two NEVER both fire. Both underlying readers degrade to `""` on
+ * missing/malformed input and never throw, so this resolver never throws.
+ */
+import { extractWikiNameFromRef, INDEX_MD, LOG_MD, loadWikiSchema, SCHEMA_MD } from "../../wiki/wiki.js";
+import { resolveStashStandards } from "./resolve-stash-standards.js";
+/** Wiki infra files that are not authored pages (relative to the wiki root). */
+const WIKI_INFRA_BASENAMES = new Set([SCHEMA_MD, INDEX_MD, LOG_MD]);
+/**
+ * Resolve the standards context for a write target identified by its asset ref.
+ *
+ * @param ref       Canonical asset ref of the write target (e.g. `skill:foo`,
+ *                  `wiki:research/topics/x`). When undefined, the target is a
+ *                  non-wiki authoring flow → stash standards.
+ * @param stashRoot Stash root directory.
+ */
+export function resolveStandardsContext(ref, stashRoot) {
+    const wikiName = ref ? extractWikiNameFromRef(ref) : undefined;
+    if (!wikiName) {
+        // Non-wiki asset target → Feature B (stash authoring standards).
+        return resolveStashStandards(stashRoot);
+    }
+    // Wiki target. Extract the page path after `wiki:<name>/`.
+    const prefix = `wiki:${wikiName}/`;
+    const pagePath = ref?.startsWith(prefix) ? ref.slice(prefix.length) : "";
+    // `wiki:<name>` with no page, a `raw/` file, or a wiki infra file → neither
+    // feature fires.
+    if (!pagePath)
+        return "";
+    if (pagePath === "raw" || pagePath.startsWith("raw/"))
+        return "";
+    // Infra files (`schema`/`index`/`log`) are only special at the WIKI ROOT.
+    // A nested page like `wiki:research/analysis/schema` is a genuine page and
+    // must NOT be suppressed, so only check when the page is at root depth.
+    if (!pagePath.includes("/")) {
+        // Refs drop the `.md` extension; compare against both forms defensively.
+        if (WIKI_INFRA_BASENAMES.has(pagePath) || WIKI_INFRA_BASENAMES.has(`${pagePath}.md`)) {
+            return "";
+        }
+    }
+    // A genuine wiki page → Feature A (that wiki's schema body).
+    return loadWikiSchema(stashRoot, wikiName).body;
+}

package/dist/core/standards/resolve-stash-standards.js

@@ -0,0 +1,87 @@
+// 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/.
+/**
+ * Resolve the stash-authoring "standards" context (Feature B of the standards
+ * plan): gather the bodies of `fact` assets whose `category` frontmatter is
+ * `convention` or `meta` so naming / tag / frontmatter conventions are surfaced
+ * to the agent when it creates or edits a non-wiki asset.
+ *
+ * Selection is by **frontmatter `category`**, never by path — flat
+ * (`facts/x.md`) and nested (`facts/conventions/x.md`) layouts resolve
+ * identically. The MVP does no parsing of fenced blocks, no rule objects, and
+ * no warnings: it concatenates the selected facts' bodies in stable enumeration
+ * order, each preceded by a one-line `# <ref>` provenance header. Returns `""`
+ * when no matching facts exist.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../asset/frontmatter.js";
+/** `category` values that mark a fact as an authoring standard. */
+const STANDARD_CATEGORIES = new Set(["convention", "meta"]);
+/** Directory (under the stash root) where `fact` assets live. */
+const FACTS_SUBDIR = "facts";
+/**
+ * Recursively collect `.md` files under `dir` in stable (sorted) enumeration
+ * order. Returns absolute paths. Missing dir → `[]`.
+ */
+function collectMarkdownFiles(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...collectMarkdownFiles(full));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+/**
+ * Derive a fact ref (`fact:conventions/naming`) from an absolute markdown path
+ * relative to the facts root. Mirrors the canonical-name derivation in
+ * `asset-spec.ts` (POSIX separators, `.md` stripped).
+ */
+function toFactRef(factsRoot, absPath) {
+    const rel = path.relative(factsRoot, absPath).split(path.sep).join("/");
+    const name = rel.endsWith(".md") ? rel.slice(0, -3) : rel;
+    return `fact:${name}`;
+}
+export function resolveStashStandards(stashRoot) {
+    const factsRoot = path.join(stashRoot, FACTS_SUBDIR);
+    const sections = [];
+    for (const absPath of collectMarkdownFiles(factsRoot)) {
+        let raw;
+        try {
+            raw = fs.readFileSync(absPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        let category = "";
+        let body = "";
+        try {
+            const parsed = parseFrontmatter(raw);
+            category = typeof parsed.data.category === "string" ? parsed.data.category.trim() : "";
+            body = parsed.content;
+        }
+        catch {
+            continue;
+        }
+        if (!STANDARD_CATEGORIES.has(category))
+            continue;
+        const trimmed = body.trim();
+        if (!trimmed)
+            continue; // skip stub facts with frontmatter but no body
+        sections.push(`# ${toFactRef(factsRoot, absPath)}\n${trimmed}`);
+    }
+    return sections.join("\n\n");
+}

package/dist/integrations/agent/prompts.js

@@ -26,6 +26,7 @@
  * during validation. We carry it through if the agent supplies it.
  */
 import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { authoringRulesForType } from "../../core/authoring-rules.js";
 import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 /**
  * Per-asset-type frontmatter / authoring hints surfaced in the prompt so
@@ -156,6 +157,17 @@ export function buildReflectPrompt(input) {
         // ref is set but no feedback — explicitly constrain scope to schema compliance
         sections.push("No usage feedback recorded. Limit your proposal to schema and structural improvements only: missing required frontmatter fields, unclear `when_to_use`, ambiguous description, or broken formatting. Do not speculate about runtime weaknesses you have not observed.");
     }
+    if (input.standardsContext?.trim()) {
+        sections.push("Standards to follow (the rulebook for this target):");
+        sections.push(input.standardsContext.trim());
+    }
+    {
+        const resolvedType = input.type ?? (input.ref?.includes(":") ? input.ref.split(":")[0] : "");
+        const authoringRules = resolvedType ? authoringRulesForType(resolvedType) : "";
+        if (authoringRules) {
+            sections.push(authoringRules);
+        }
+    }
     if (input.assetContent?.trim()) {
         // Cap at 12 000 chars to stay well under OS ARG_MAX when the prompt is
         // passed as a CLI argument to opencode/claude. Large assets (wiki snapshots,
@@ -289,6 +301,16 @@ export function buildProposePrompt(input) {
         for (const line of input.schemaHints)
             sections.push(`- ${line}`);
     }
+    if (input.standardsContext?.trim()) {
+        sections.push("Standards to follow (the rulebook for this target):");
+        sections.push(input.standardsContext.trim());
+    }
+    {
+        const authoringRules = authoringRulesForType(input.type);
+        if (authoringRules) {
+            sections.push(authoringRules);
+        }
+    }
     sections.push("Produce a single proposal that, if accepted, would land as the asset described above.");
     sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
     return sections.join("\n\n");
@@ -305,6 +327,16 @@ export function buildSchemaRepairPrompt(input) {
         `while preserving all existing content.`);
     sections.push(`Target ref: ${input.ref}`);
     sections.push(`Schema requirements for ${input.type} assets: ${hintForType(input.type)}`);
+    if (input.standardsContext?.trim()) {
+        sections.push("Standards to follow (the rulebook for this target):");
+        sections.push(input.standardsContext.trim());
+    }
+    {
+        const authoringRules = authoringRulesForType(input.type);
+        if (authoringRules) {
+            sections.push(authoringRules);
+        }
+    }
     const CONTENT_CAP = 3000;
     const body = input.assetContent.trimEnd();
     const truncated = body.length > CONTENT_CAP;

package/dist/wiki/wiki.js

@@ -224,6 +224,43 @@ function readSchemaDescription(wikiDir) {
         return undefined;
     }
 }
+/**
+ * Load a wiki's `schema.md` body and frontmatter.
+ *
+ * Unlike {@link readSchemaDescription} (which returns only the frontmatter
+ * `description` for `listWikis` summaries), this returns the markdown **body**
+ * — everything after the closing `---` of the frontmatter — which is where the
+ * page contract, operations, and hard rules live. The body is the rulebook
+ * injected into the write-time prompt for wiki-page edits.
+ *
+ * Swallow-and-degrade like the existing reader: a missing file, an unresolvable
+ * wiki dir, or malformed content yields `{ body: "", frontmatter: {} }`. Never
+ * throws.
+ */
+export function loadWikiSchema(stashRoot, name) {
+    const empty = { body: "", frontmatter: {} };
+    let wikiDir;
+    try {
+        wikiDir = resolveWikiDir(stashRoot, name);
+    }
+    catch {
+        return empty;
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(wikiDir, SCHEMA_MD), "utf8");
+    }
+    catch {
+        return empty;
+    }
+    try {
+        const parsed = parseFrontmatter(raw);
+        return { body: parsed.content, frontmatter: parsed.data };
+    }
+    catch {
+        return empty;
+    }
+}
 function toIsoDate(ms) {
     return new Date(ms).toISOString();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.35",
+  "version": "0.9.0-beta.36",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [