akm-cli 0.9.0-beta.5 → 0.9.0-beta.51

package/dist/core/config/config.js

@@ -221,7 +221,18 @@ function maybeAutoMigrateConfigFile(configPath, text) {
     catch {
         return text; // Malformed JSON — let parseAndValidate surface the error.
     }
-    if (compareConfigVersion(obj.configVersion, CURRENT_CONFIG_VERSION) === 1) {
+    // Downgrade protection. Skip migration when the on-disk config is NEWER than
+    // this binary (=== 1), OR when it carries a configVersion we cannot order
+    // against ours (compareConfigVersion returns undefined for an unparseable
+    // value — e.g. one written by a newer/foreign akm). Migrating such a config
+    // could strip fields a newer binary added, a cross-version data-loss path.
+    //
+    // A MISSING configVersion (absent → undefined) is a legacy pre-versioning
+    // config that MUST still migrate, so the unparseable-skip is gated on the
+    // field being PRESENT (`onDiskVersion !== undefined`).
+    const onDiskVersion = obj.configVersion;
+    const versionOrder = compareConfigVersion(onDiskVersion, CURRENT_CONFIG_VERSION);
+    if (versionOrder === 1 || (onDiskVersion !== undefined && versionOrder === undefined)) {
         return text;
     }
     const { changed, result } = migrateConfigShape(obj);
@@ -249,8 +260,8 @@ function maybeAutoMigrateConfigFile(configPath, text) {
             "  to preview a dry-run diff:            akm config migrate --dry-run --print-diff",
             "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
         ].join("\n");
-        process.stderr.write(`${banner}\n`);
-        process.stdout.write(`${banner}\n`);
+        process.stderr?.write?.(`${banner}\n`);
+        process.stdout?.write?.(`${banner}\n`);
     }
     catch (err) {
         // #461: never return migrated bytes when disk write fails — that triggers
@@ -273,9 +284,14 @@ export function saveConfig(config) {
     const dir = path.dirname(configPath);
     fs.mkdirSync(dir, { recursive: true });
     const sanitized = sanitizeConfigForWrite(config);
-    // Final validation gate before bytes hit disk. Catches schema violations
-    // (unknown keys in registries[] / sources[] / profiles.*; out-of-range
-    // numbers; etc. — closes #462) before we corrupt the user's config.
+    // Final validation gate before bytes hit disk. Runs the FULL schema —
+    // including the cross-field superRefine guards (removed `feedbackDistillation`
+    // process key, `defaultWriteTarget` resolution, writable npm/website sources)
+    // and all type/enum/range checks — so an `akm config set` (leaf OR object
+    // form) cannot persist a guard-violating or mistyped value. NOTE: unknown
+    // keys are intentionally NOT rejected here — object schemas are `.passthrough()`
+    // so cross-version skew round-trips (see config-schema.ts header); the lenient
+    // tolerance is by design, not an oversight.
     const parseResult = AkmConfigSchema.safeParse(sanitized);
     if (!parseResult.success) {
         const lines = parseResult.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
@@ -450,7 +466,12 @@ function applyRuntimeEnvApiKeys(config) {
     }
     // LLM profile keys: AKM_LLM_API_KEY for the default profile, then
     // AKM_PROFILE_<UPPER>_API_KEY for any profile (per-profile wins).
-    const defaultProfile = next.defaults?.llm;
+    // Resolve the default profile the SAME way the rest of the config layer does
+    // (resolveDefaultLlmProfileName), so the implicit `profiles.llm.default`
+    // fallback is honored. Keying off the raw `defaults.llm` field alone silently
+    // dropped AKM_LLM_API_KEY for configs that rely on the implicit default —
+    // the same no-op-run class as the 2026-05-23 incident.
+    const defaultProfile = resolveDefaultLlmProfileName(next);
     if (next.profiles?.llm) {
         const updated = { ...next.profiles.llm };
         let changed = false;

package/dist/core/events.js

@@ -27,7 +27,7 @@
 import path from "node:path";
 import { rethrowIfTestIsolationError } from "./errors.js";
 import { getDataDir } from "./paths.js";
-import { insertEvent, openStateDatabase, readStateEvents } from "./state-db.js";
+import { insertEvent, openStateDatabase, readStateEvents, withStateDb } from "./state-db.js";
 import { error } from "./warn.js";
 /**
  * Legacy events.jsonl path — used only by the migration script
@@ -82,18 +82,14 @@ export function appendEvent(input, ctx) {
     // Default path: open, insert, close.
     const dbPath = resolveDbPath(ctx);
     try {
-        const db = openStateDatabase(dbPath);
-        try {
+        withStateDb((db) => {
             insertEvent(db, {
                 eventType: input.eventType,
                 ts,
                 ref: input.ref,
                 metadata: input.metadata,
             });
-        }
-        finally {
-            db.close();
-        }
+        }, { path: dbPath });
     }
     catch (err) {
         // Never mask the bun-test isolation guard as a silent "events failed".

package/dist/core/improve-types.js

@@ -11,16 +11,18 @@ import { assertNever } from "./assert.js";
  *
  * Buckets:
  * - `accepted` — a write/content-authoring action succeeded.
- * - `rejected` — the action was deliberately not applied (cooldown, skip,
- *   distill-skip, or a content-policy guard rejection). NOTE: as of the
- *   round-2 health pass `reflect-guard-rejected` is bucketed here. Previously
- *   the `state-db.ts` switch omitted it entirely (no case, no default), so a
- *   guard rejection silently vanished from accepted/rejected/error totals — a
- *   data-integrity miscount. It is a deliberate non-application of the action,
- *   so it belongs with the other "rejected" outcomes.
+ * - `skipped` — the ref was GATED OUT before any content was produced: a
+ *   cooldown, a signal-delta/eligibility skip, or a distill pool-delta skip.
+ *   These are NOT rejections of produced content — they are the run declining
+ *   to act on a ref it had no new reason to touch, and they scale with the
+ *   whole indexed-ref pool (~13k/run), so folding them into `rejected` made the
+ *   "accept rate" meaningless (deep-tuning analysis 2026-06-29, finding #1).
+ * - `rejected` — the run PRODUCED a change and a content-policy guard then
+ *   rejected it (`reflect-guard-rejected`). This is the genuine value-rejection
+ *   signal; it is small and meaningful, no longer drowned by gated skips.
  * - `error` — the action failed (LLM/runtime error).
  * - `noop` — bookkeeping that is neither a write nor a rejection (memory-prune);
- *   intentionally counted in none of the three numeric buckets.
+ *   intentionally counted in none of the numeric buckets.
  *
  * The `default: assertNever(mode)` arm makes any future union variant a
  * compile-time error here, forcing an explicit bucket choice.
@@ -35,6 +37,7 @@ export function classifyImproveAction(mode) {
         case "reflect-cooldown":
         case "reflect-skipped":
         case "distill-skipped":
+            return "skipped";
         case "reflect-guard-rejected":
             return "rejected";
         case "reflect-failed":

package/dist/core/logs-db.js

@@ -16,8 +16,10 @@
  * Log lines are high-volume, append-only, and freely purgeable; state.db rows
  * (events, proposals, task_history) are durable records. Separating them keeps
  * state.db small and lets log retention be aggressive without touching durable
- * state. Cross-db queries (e.g. "failed task_history row → its log lines") use
- * SQLite ATTACH — see {@link attachStateDatabase}.
+ * state. Callers that need to correlate a task_history row with its log lines do
+ * an application-side join on the {@link buildTaskRunId} key (e.g. `health` via
+ * {@link getLoggedRunIds}) — no SQLite ATTACH, so the split survives a future
+ * provider change.
  *
  * ## run_id
  *
@@ -39,8 +41,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { openDatabase } from "../storage/database.js";
 import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
 import { getDataDir } from "./paths.js";
-import { getStateDbPath } from "./state-db.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
  * Default path: `<dataDir>/logs.db` — alongside state.db so cooperating
@@ -75,9 +77,9 @@ export function openLogsDatabase(dbPath) {
         fs.mkdirSync(dir, { recursive: true });
     }
     const db = openDatabase(resolvedPath);
-    // PRAGMAs must run before any DDL or DML.
-    db.exec("PRAGMA journal_mode = WAL");
-    db.exec("PRAGMA busy_timeout = 30000");
+    // PRAGMAs must run before any DDL or DML. foreignKeys:false preserves this
+    // opener's historical behaviour — logs.db has never enforced foreign keys.
+    applyStandardPragmas(db, { dataDir: dir, foreignKeys: false });
     runMigrations(db);
     return db;
 }
@@ -145,8 +147,8 @@ export function runMigrations(db) {
  * Encode a task run's identity — the unique `(task_id, started_at)` pair from
  * state.db `task_history` — as a single run_id string.
  *
- * The format MUST stay in sync with the SQL expression
- * `task_id || '@' || started_at` used by {@link queryFailedRunLogLines}.
+ * The format MUST stay in sync with the application-side join key that callers
+ * build from a `task_history` row's `task_id` and `started_at`.
  */
 export function buildTaskRunId(taskId, startedAtIso) {
     return `${taskId}@${startedAtIso}`;
@@ -229,64 +231,6 @@ export function getLoggedRunIds(db, runIds) {
     }
     return out;
 }
-// ── Cross-db: ATTACH state.db ────────────────────────────────────────────────
-/**
- * ATTACH state.db to an open logs.db handle under the schema name `state`,
- * enabling cross-db joins like task_history × task_logs.
- *
- * The state.db file must already exist (callers always open state.db first in
- * practice); attaching a non-existent path would silently create an empty,
- * unmigrated database file, so this throws instead.
- */
-export function attachStateDatabase(db, stateDbPath) {
-    const resolved = stateDbPath ?? getStateDbPath();
-    if (!fs.existsSync(resolved)) {
-        throw new Error(`Cannot ATTACH state.db: file does not exist at ${resolved}`);
-    }
-    // prepare().run() rather than db.run(): both drivers support parameterised
-    // ATTACH through a prepared statement, and no other call site uses db.run().
-    db.prepare("ATTACH DATABASE ? AS state").run(resolved);
-}
-/**
- * Convenience: open logs.db with state.db attached as `state`. The returned
- * handle supports cross-db queries such as {@link queryFailedRunLogLines}.
- * Close it like any other handle (DETACH is implicit on close).
- */
-export function openLogsDatabaseWithState(logsDbPath, stateDbPath) {
-    const db = openLogsDatabase(logsDbPath);
-    try {
-        attachStateDatabase(db, stateDbPath);
-    }
-    catch (err) {
-        db.close();
-        throw err;
-    }
-    return db;
-}
-/**
- * Cross-db join: every log line belonging to a FAILED task_history run whose
- * `started_at` is `>= since` (all failed runs when omitted). Requires a handle
- * opened via {@link openLogsDatabaseWithState}.
- *
- * The join key is the run_id encoding documented on {@link buildTaskRunId}:
- * `task_logs.run_id = task_history.task_id || '@' || task_history.started_at`.
- */
-export function queryFailedRunLogLines(db, options = {}) {
-    const conditions = ["th.status = 'failed'"];
-    const params = [];
-    if (options.since) {
-        conditions.push("th.started_at >= ?");
-        params.push(options.since);
-    }
-    const limit = options.limit !== undefined && options.limit >= 0 ? ` LIMIT ${Math.floor(options.limit)}` : "";
-    return db
-        .prepare(`SELECT th.task_id, l.run_id, th.started_at, th.status, l.ts, l.stream, l.level, l.line
-       FROM state.task_history th
-       JOIN task_logs l ON l.run_id = th.task_id || '@' || th.started_at
-       WHERE ${conditions.join(" AND ")}
-       ORDER BY th.started_at DESC, l.id ASC${limit}`)
-        .all(...params);
-}
 // ── Retention ────────────────────────────────────────────────────────────────
 /**
  * Delete task_logs rows older than `retentionDays` (default: 90). Mirrors

package/dist/core/parse.js

@@ -98,16 +98,24 @@ export function parseJsonResponse(raw) {
  * balanced `{ }` or `[ ]` structure in the text and attempts to parse that
  * substring. Returns `undefined` if no valid JSON structure is found.
  *
- * Non-array results are preferred: if a `{…}` object is found first, it is
- * returned immediately. Arrays (`[…]`) are captured as a fallback and
- * returned only when no object was found.
+ * Shape preference is controlled by {@link ParseEmbeddedJsonOptions.expect}:
+ * - `"any"` (default): non-array results are preferred — a `{…}` object found
+ *   first is returned immediately; arrays (`[…]`) are a fallback.
+ * - `"array"`: only top-level arrays are returned. The direct parse is
+ *   accepted only if it is an array, and the scanner returns the first
+ *   balanced `[…]` while skipping `{…}` openers entirely.
  */
-export function parseEmbeddedJsonResponse(raw) {
+export function parseEmbeddedJsonResponse(raw, options) {
+    const expectArray = options?.expect === "array";
     const direct = parseJsonResponse(raw);
-    if (direct !== undefined)
+    if (direct !== undefined && (!expectArray || Array.isArray(direct)))
         return direct;
     const text = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(raw)));
     let arrayFallback;
+    // Scan only *top-level* balanced structures: once a `{…}`/`[…]` is matched we
+    // jump `start` past its closing bracket rather than re-scanning its interior.
+    // This keeps array mode from salvaging an array *nested inside* a leading
+    // object (e.g. the `entities` array of a bare `{entities,relations}` object).
     for (let start = 0; start < text.length; start++) {
         const opener = text[start];
         if (opener !== "{" && opener !== "[")
@@ -116,6 +124,7 @@ export function parseEmbeddedJsonResponse(raw) {
         let depth = 0;
         let inString = false;
         let escaped = false;
+        let end = -1;
         for (let i = start; i < text.length; i++) {
             const ch = text[i];
             if (inString) {
@@ -139,20 +148,31 @@ export function parseEmbeddedJsonResponse(raw) {
             if (ch === closer) {
                 depth -= 1;
                 if (depth === 0) {
-                    try {
-                        const parsed = JSON.parse(text.slice(start, i + 1));
-                        if (!Array.isArray(parsed)) {
-                            return parsed;
-                        }
-                        arrayFallback ??= parsed;
-                        break;
-                    }
-                    catch {
-                        break;
-                    }
+                    end = i;
+                    break;
                 }
             }
         }
+        if (end === -1)
+            continue; // never balanced — let the next opener try
+        try {
+            const parsed = JSON.parse(text.slice(start, end + 1));
+            if (Array.isArray(parsed)) {
+                // First valid array wins in array mode; in "any" mode it is the
+                // fallback returned only if no object is found.
+                if (expectArray)
+                    return parsed;
+                arrayFallback ??= parsed;
+            }
+            else if (!expectArray) {
+                return parsed;
+            }
+            // Skip past this balanced structure so we don't descend into it.
+            start = end;
+        }
+        catch {
+            // Malformed candidate — advance one char and try the next opener.
+        }
     }
     return arrayFallback;
 }

package/dist/core/paths.js

@@ -215,6 +215,9 @@ export function getDataDir(env = process.env, platform = process.platform) {
 export function getDbPath() {
     return path.join(getDataDir(), "index.db");
 }
+export function getIndexWriterLockPath() {
+    return path.join(getDataDir(), "index.db.write.lock");
+}
 export function getWorkflowDbPath() {
     return path.join(getDataDir(), "workflow.db");
 }

package/dist/core/standards/resolve-standards-context.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/.
+/**
+ * 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";
+import { resolveTypeConventions, typeConventionRef } from "./resolve-type-conventions.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]);
+/**
+ * Extract the asset type from a canonical ref (`[origin//]type:name`) without
+ * throwing. Returns `undefined` for refs that have no `type:` prefix. Kept local
+ * and lenient — the per-type resolver validates the result against
+ * `getAssetTypes()`, so a bogus prefix here simply yields no convention.
+ */
+function refType(ref) {
+    if (!ref)
+        return undefined;
+    const body = ref.includes("//") ? ref.slice(ref.indexOf("//") + 2) : ref;
+    const colon = body.indexOf(":");
+    if (colon <= 0)
+        return undefined;
+    return body.slice(0, colon).trim() || undefined;
+}
+/**
+ * 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 (general stash standards) plus the
+        // per-type SOFT conventions layer (#646), type-scoped to the write target.
+        const general = resolveStashStandards(stashRoot);
+        const type = refType(ref);
+        // A non-empty body here guarantees `type` is a `getAssetTypes()`-validated
+        // string (the resolver returns "" otherwise).
+        const typeConventions = type ? resolveTypeConventions(stashRoot, type) : "";
+        if (!typeConventions || !type)
+            return general;
+        // Soft, type-scoped guidance — clearly labeled and kept separate from the
+        // HARD (validator-enforced) rules that `authoringRulesForType` injects
+        // downstream. These facts are advice only; they never weaken the gate.
+        const softSection = [
+            `# ${typeConventionRef(type)} (soft per-type conventions — guidance, not enforced)`,
+            typeConventions,
+        ].join("\n");
+        return general ? `${general}\n\n${softSection}` : softSection;
+    }
+    // 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,99 @@
+// 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";
+/**
+ * Per-type SOFT convention facts (`facts/conventions/assets/<type>.md`, #646)
+ * are surfaced **type-scoped** through `resolveTypeConventions`, so they must
+ * NOT leak into this un-type-scoped general layer (authoring a `command` must
+ * not pull the `skill` convention). Excluded by relative path (POSIX form).
+ */
+const TYPE_CONVENTIONS_REL = "conventions/assets/";
+/**
+ * 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)) {
+        // Per-type SOFT conventions are delivered type-scoped (#646); skip them
+        // here so they never leak un-type-scoped into every authoring flow.
+        const relPosix = path.relative(factsRoot, absPath).split(path.sep).join("/");
+        if (relPosix.startsWith(TYPE_CONVENTIONS_REL))
+            continue;
+        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/standards/resolve-type-conventions.js

@@ -0,0 +1,66 @@
+// 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 **per-type SOFT authoring conventions** (#646) — the third and final
+ * authoring-guidance layer:
+ *
+ *   1. HARD rules (validator-rejecting, code-sourced) → `authoringRulesForType()`
+ *      (`src/core/authoring-rules.ts`, #645). Never editable; the gate enforces them.
+ *   2. General stash standards (cross-type naming/tag conventions) →
+ *      `resolveStashStandards()` `category: convention|meta` facts (#642).
+ *   3. **Per-type SOFT conventions** (voice, structure, length *preference* for
+ *      *this* asset type) → user-editable `facts/conventions/assets/<type>.md`
+ *      (THIS module). Augments the built-in `TYPE_HINTS` fallback for display.
+ *
+ * These facts are **soft only** — advice, not contract. They MUST NOT carry
+ * hard, validator-rejecting rules: a user editing or deleting one must never be
+ * able to weaken the authoring contract the gate enforces (#645 boundary).
+ *
+ * Selection is by a `getAssetTypes()`-validated basename: only
+ * `facts/conventions/assets/<known-type>.md` resolves. Read directly from disk
+ * (no index rebuild); any missing dir/file, unknown type, or read error degrades
+ * to `""` and never throws.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getAssetTypes } from "../asset/asset-spec.js";
+import { parseFrontmatter } from "../asset/frontmatter.js";
+/** Sub-path (under the stash root) for per-type SOFT convention facts. */
+export const TYPE_CONVENTIONS_SUBDIR = path.join("facts", "conventions", "assets");
+/** The `fact:` ref prefix for a per-type convention, e.g. `fact:conventions/assets/skill`. */
+export function typeConventionRef(type) {
+    return `fact:conventions/assets/${type}`;
+}
+/**
+ * Read the SOFT authoring-convention body for asset type `type`, if a stash
+ * owner has authored `facts/conventions/assets/<type>.md`.
+ *
+ * @returns the trimmed markdown body (frontmatter stripped), or `""` when the
+ *          type is unknown, the file is absent, or anything goes wrong.
+ */
+export function resolveTypeConventions(stashRoot, type) {
+    if (!stashRoot || !type)
+        return "";
+    // Basename MUST be a known asset type — never resolve an arbitrary file.
+    if (!getAssetTypes().includes(type))
+        return "";
+    const abs = path.join(stashRoot, TYPE_CONVENTIONS_SUBDIR, `${type}.md`);
+    let raw;
+    try {
+        raw = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return ""; // missing dir/file or read error → degrade to empty
+    }
+    let body = "";
+    try {
+        body = parseFrontmatter(raw).content;
+    }
+    catch {
+        // Malformed frontmatter: fall back to the whole file (parseFrontmatter
+        // normally returns whole content as body, but guard defensively).
+        body = raw;
+    }
+    return body.trim();
+}