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

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/config/config-schema.js

@@ -208,6 +208,11 @@ export const ImproveProcessConfigSchema = z
     maxSessionsPerRun: z.number().int().min(0).optional(),
     // #561 — index agent sessions as a searchable `session` asset (extract
     // process). Absent = on-when-an-LLM-is-available (fail-open when offline).
+    // COST: when on, each processed session makes a SECOND LLM call (the session
+    // summary) on top of the extraction call — i.e. ~2 LLM calls/session. Set to
+    // false to halve per-session extract cost at the price of unsearchable
+    // sessions. (Unchanged/skip sessions still cost zero — the content-hash
+    // ledger gates both calls upstream.)
     indexSessions: z.boolean().optional(),
     // #561 — minimum session duration in minutes for session indexing. 0
     // disables the gate. Absent = default 5. Only meaningful on `extract`.

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/core/state-db.js

@@ -1520,6 +1520,23 @@ export function getExtractedSessionsMap(db, harness, sessionIds) {
     }
     return out;
 }
+/**
+ * The most recent extract-run time for a harness — `MAX(processed_at)` across
+ * its ledger rows, as ms epoch — or `null` when the harness has never been
+ * extracted. Used to default the discovery window to "since the last run" so an
+ * intermittently-online host that was off for days still rediscovers sessions
+ * that ended during the gap (the content-hash ledger keeps the widened window
+ * free of redundant LLM cost).
+ */
+export function getLastExtractRunAt(db, harness) {
+    const row = db
+        .prepare("SELECT MAX(processed_at) AS last FROM extract_sessions_seen WHERE harness = ?")
+        .get(harness);
+    if (!row?.last)
+        return null;
+    const ms = Date.parse(row.last);
+    return Number.isFinite(ms) ? ms : null;
+}
 /**
  * Decide whether a session should be skipped because the extractor has already
  * processed BYTE-IDENTICAL content (#602). The skip authority is the content

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/scripts/migrate-storage.js

@@ -8998,6 +8998,7 @@ __export(exports_state_db, {
   getStateDbPath: () => getStateDbPath,
   getRecombineHypothesis: () => getRecombineHypothesis,
   getPhaseThreshold: () => getPhaseThreshold,
+  getLastExtractRunAt: () => getLastExtractRunAt,
   getExtractedSessionsMap: () => getExtractedSessionsMap,
   getExtractedSession: () => getExtractedSession,
   getConsolidationJudgedMap: () => getConsolidationJudgedMap,
@@ -9437,6 +9438,13 @@ function getExtractedSessionsMap(db, harness, sessionIds) {
   }
   return out;
 }
+function getLastExtractRunAt(db, harness) {
+  const row = db.prepare("SELECT MAX(processed_at) AS last FROM extract_sessions_seen WHERE harness = ?").get(harness);
+  if (!row?.last)
+    return null;
+  const ms = Date.parse(row.last);
+  return Number.isFinite(ms) ? ms : null;
+}
 function shouldSkipAlreadyExtractedSession(prior, currentContentHash) {
   if (!prior)
     return false;

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.34",
+  "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": [