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

package/CHANGELOG.md

@@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- **Per-type SOFT authoring conventions are now user-editable stash facts.** A
+  third authoring-guidance layer joins the hard rules (#645) and general stash
+  standards (#642): a stash owner can author
+  `facts/conventions/assets/<type>.md` (e.g. `…/skill.md`, `…/command.md`) to
+  capture soft, type-specific guidance — voice, structure, length *preference*,
+  naming style. When an agent authors a `skill:x`, the body of
+  `fact:conventions/assets/skill` is injected (type-scoped — authoring
+  `command:y` pulls the `command` convention, never the `skill` one), labeled
+  as soft guidance and kept separate from the validator-enforced hard rules.
+  The basename must be a `getAssetTypes()`-validated asset type; facts are read
+  straight from disk (no index rebuild) and degrade to empty safely. When no
+  per-type fact exists, the built-in `TYPE_HINTS` fallback is unchanged (no
+  regression). These facts carry soft conventions only and can never weaken the
+  authoring contract the gate enforces (`authoringRulesForType` remains the sole
+  source of validator-rejecting rules). The general convention/meta resolver now
+  excludes `facts/conventions/assets/*` so per-type guidance never leaks
+  un-type-scoped into other authoring flows. (#646)
+
 ## [0.9.0-beta.36] — 2026-06-22
 
 ### Added

package/dist/commands/improve/improve.js

@@ -54,7 +54,7 @@ import { DEFAULT_DUE_DAYS, DEFAULT_MAX_PER_RUN, filterProactiveDue, selectProact
 import { akmProcedural } from "./procedural.js";
 import { akmRecombine } from "./recombine.js";
 import { akmReflect } from "./reflect.js";
-import { buildRankChangeReport, computeSalience, getAllRankScores, getAssetSalience, getConsecutiveNoOps, getLastUseMsByRef, recordNoOp, resetConsecutiveNoOps, SALIENCE_NO_OP_DAMPEN_FACTOR, SALIENCE_NO_OP_DAMPEN_THRESHOLD, upsertAssetSalience, } from "./salience.js";
+import { buildRankChangeReport, computeSalience, getAllRankScores, getAssetSalience, getConsecutiveNoOps, getLastUseMsByRef, isContentEncodingRow, recordNoOp, resetConsecutiveNoOps, SALIENCE_NO_OP_DAMPEN_FACTOR, SALIENCE_NO_OP_DAMPEN_THRESHOLD, upsertAssetSalience, } from "./salience.js";
 // #607 Lock Decomposition: fine-grained per-process locks replace the single
 // `improve.lock`. Three independent locks allow concurrent improve runs when
 // they touch different subsystems (e.g. quick-shredder consolidate can run
@@ -2733,6 +2733,37 @@ async function runImprovePreparationStage(args) {
     const outcomeWeightEnabled = salienceConfig?.outcomeWeightEnabled === true;
     const salienceMap = new Map();
     const nowForSalience = Date.now();
+    // #644 — preserve content-derived encoding scores across runs.
+    //
+    // Before computing the salience vector, load each ref's stored encoding score
+    // and its provenance. When the stored row carries a genuine content-derived
+    // score (written by the distill path via `scoreEncodingSalience`), pass that
+    // value back in as `inputs.encodingSalience` so `computeSalience` does NOT fall
+    // back to the type-weight stub — keeping both the persisted `encoding_salience`
+    // AND the derived `rank_score` keyed on real novelty/magnitude/prediction-error.
+    // Refs that have never been content-scored keep the type-weight stub fallback.
+    const storedEncodingByRef = new Map();
+    {
+        let dbForStoredEncoding;
+        try {
+            dbForStoredEncoding = openStateDatabase(eventsCtx?.dbPath);
+            for (const r of mergedRefs) {
+                const type = r.ref.includes(":") ? r.ref.slice(0, r.ref.indexOf(":")) : "";
+                const row = getAssetSalience(dbForStoredEncoding, r.ref);
+                if (row && isContentEncodingRow(row, type)) {
+                    storedEncodingByRef.set(r.ref, row.encoding_salience);
+                }
+            }
+        }
+        catch (err) {
+            rethrowIfTestIsolationError(err);
+            // best-effort: if DB unavailable, fall back to type-weight stub (prior behaviour)
+        }
+        finally {
+            if (dbForStoredEncoding)
+                dbForStoredEncoding.close();
+        }
+    }
     for (const r of mergedRefs) {
         const type = r.ref.includes(":") ? r.ref.slice(0, r.ref.indexOf(":")) : "";
         const sizeBytes = (() => {
@@ -2746,9 +2777,13 @@ async function runImprovePreparationStage(args) {
                 return undefined;
             }
         })();
+        const storedEncoding = storedEncodingByRef.get(r.ref);
         const vector = computeSalience({
             ref: r.ref,
             type,
+            // #644: pass the stored content-derived score (if any) so the type-weight
+            // stub is NOT re-asserted over a real distill-written encoding score.
+            ...(storedEncoding !== undefined ? { encodingSalience: storedEncoding } : {}),
             retrievalFreq: retrievalCounts.get(r.ref) ?? 0,
             lastUseMs: lastUseMsByRef.get(r.ref),
             utilityScore: utilityMap.get(r.ref),

package/dist/commands/improve/salience.js

@@ -126,6 +126,7 @@ export function computeSalience(inputs) {
     // Fall back to the type-importance stub only when the caller has not yet
     // computed a content-based score (e.g. on older assets before the first
     // staleness refresh runs).
+    const encodingSource = inputs.encodingSalience !== undefined ? "content" : "type-stub";
     const encoding = inputs.encodingSalience !== undefined
         ? Math.min(1, Math.max(0, inputs.encodingSalience))
         : (DEFAULT_TYPE_ENCODING_WEIGHTS[inputs.type] ?? DEFAULT_ENCODING_SALIENCE);
@@ -213,24 +214,75 @@ export function computeSalience(inputs) {
     }
     const rawRankScore = (we * encoding + wo * outcome + wr * retrieval) * sizePenalty;
     const rankScore = Math.min(1, Math.max(0, rawRankScore));
-    return { encoding, outcome, retrieval, rankScore };
+    return { encoding, outcome, retrieval, rankScore, encodingSource };
+}
+/**
+ * Does this row carry a genuine content-derived `encoding_salience` (#644)?
+ *
+ * Returns true when the provenance flag is `"content"`. For legacy rows
+ * (`encoding_source === null`, written before migration 015) we apply a
+ * conservative heuristic: treat the stored value as content-derived only when it
+ * does NOT equal the pure type-weight stub for the asset's type — because before
+ * the #644 fix every run overwrote real scores with the stub, a value that still
+ * differs from the stub must have been content-written and never re-clobbered.
+ * When the type cannot be determined (no `type` given) a null-provenance row is
+ * treated as a stub (the safe default).
+ */
+export function isContentEncodingRow(row, type) {
+    if (row.encoding_source === "content")
+        return true;
+    if (row.encoding_source === "type-stub")
+        return false;
+    // Legacy NULL provenance: differ-from-stub heuristic.
+    if (!type)
+        return false;
+    const stub = DEFAULT_TYPE_ENCODING_WEIGHTS[type] ?? DEFAULT_ENCODING_SALIENCE;
+    return Math.abs(row.encoding_salience - stub) > 1e-9;
 }
 /**
  * Upsert salience scores for one asset into state.db.
  *
- * Idempotent: safe to call every run; updates all columns on conflict.
+ * Idempotent: safe to call every run; updates the outcome / retrieval / rank
+ * columns on conflict.
+ *
+ * #644 — encoding provenance guard: the `encoding_salience` + `encoding_source`
+ * columns are NOT lowered from a real content-derived score to a type-weight
+ * stub. When the stored row is `encoding_source = 'content'` and the incoming
+ * vector is a `type-stub` fallback, the stored encoding score and its provenance
+ * are preserved (only the other sub-scores and `rank_score` advance). A `content`
+ * write always wins; a `type-stub` write only seeds a row that has no content
+ * score yet. This stops the improve loop's type-weight fallback re-asserting the
+ * stub over a distill-written score on every run.
+ *
+ * NOTE: when the guard preserves the stored encoding score, the incoming
+ * `vector.rankScore` (computed from the stub encoding) is still written. Callers
+ * that want the rank_score to reflect the preserved content score should pass the
+ * stored content score back in as `inputs.encodingSalience` to `computeSalience`
+ * — which the improve loop does. The guard here is the defensive backstop.
  */
 export function upsertAssetSalience(db, ref, vector, now) {
     const ts = now ?? Date.now();
     db.prepare(`INSERT INTO asset_salience
-       (asset_ref, encoding_salience, outcome_salience, retrieval_salience, rank_score, consecutive_no_ops, updated_at)
-     VALUES (?, ?, ?, ?, ?, 0, ?)
+       (asset_ref, encoding_salience, outcome_salience, retrieval_salience, rank_score, consecutive_no_ops, updated_at, encoding_source)
+     VALUES (?, ?, ?, ?, ?, 0, ?, ?)
      ON CONFLICT(asset_ref) DO UPDATE SET
-       encoding_salience  = excluded.encoding_salience,
+       -- #644: never lower a real content-derived score to a type-weight stub.
+       -- Keep the stored encoding score + provenance when the stored row is
+       -- 'content' and the incoming write is a 'type-stub' fallback.
+       encoding_salience  = CASE
+         WHEN asset_salience.encoding_source = 'content' AND excluded.encoding_source = 'type-stub'
+           THEN asset_salience.encoding_salience
+           ELSE excluded.encoding_salience
+       END,
+       encoding_source    = CASE
+         WHEN asset_salience.encoding_source = 'content' AND excluded.encoding_source = 'type-stub'
+           THEN asset_salience.encoding_source
+           ELSE excluded.encoding_source
+       END,
        outcome_salience   = excluded.outcome_salience,
        retrieval_salience = excluded.retrieval_salience,
        rank_score         = excluded.rank_score,
-       updated_at         = excluded.updated_at`).run(ref, vector.encoding, vector.outcome, vector.retrieval, vector.rankScore, ts);
+       updated_at         = excluded.updated_at`).run(ref, vector.encoding, vector.outcome, vector.retrieval, vector.rankScore, ts, vector.encodingSource ?? "type-stub");
 }
 /**
  * Load the salience row for one asset, or undefined if not yet computed.
@@ -238,7 +290,7 @@ export function upsertAssetSalience(db, ref, vector, now) {
 export function getAssetSalience(db, ref) {
     const row = db
         .prepare(`SELECT asset_ref, encoding_salience, outcome_salience, retrieval_salience,
-              rank_score, consecutive_no_ops, updated_at
+              rank_score, consecutive_no_ops, updated_at, encoding_source
        FROM asset_salience WHERE asset_ref = ?`)
         .get(ref);
     // Bun SQLite returns null (not undefined) when no row found.

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

@@ -17,8 +17,24 @@
  */
 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.
  *
@@ -30,8 +46,23 @@ const WIKI_INFRA_BASENAMES = new Set([SCHEMA_MD, INDEX_MD, LOG_MD]);
 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);
+        // 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}/`;

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

@@ -21,6 +21,13 @@ import { parseFrontmatter } from "../asset/frontmatter.js";
 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 → `[]`.
@@ -59,6 +66,11 @@ 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");

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();
+}

package/dist/core/state-db.js

@@ -791,6 +791,31 @@ const MIGRATIONS = [
         ON recombine_hypotheses(last_seen_at);
     `,
     },
+    // ── Migration 015 — asset_salience: encoding_source provenance column (#644) ──
+    //
+    // Records HOW the stored `encoding_salience` was derived so an improve run's
+    // type-weight fallback can no longer clobber a real content-derived score:
+    //
+    //   "content"   — written by the distill path from `scoreEncodingSalience`
+    //                 (novelty·0.40 + magnitude·0.35 + predictionError·0.25).
+    //   "type-stub" — written by `computeSalience`'s `DEFAULT_TYPE_ENCODING_WEIGHTS`
+    //                 fallback (no content-based score available for this ref yet).
+    //   NULL        — legacy row written before this migration; provenance unknown.
+    //                 Treated as a stub by readers UNLESS its stored value differs
+    //                 from the pure type-weight (best-effort heuristic for old data).
+    //
+    // Why a column rather than inference: before #644, every improve run overwrote
+    // the distill-written content score with the type-weight stub, so the stored
+    // value alone cannot distinguish a real score from a stub. The provenance flag
+    // is the single source of truth going forward; `upsertAssetSalience` refuses to
+    // lower a "content" row to a "type-stub" so the high-salience gate (#608) keys
+    // on genuine novelty/magnitude/prediction-error, not the asset type.
+    {
+        id: "015-asset-salience-encoding-source",
+        up: `
+      ALTER TABLE asset_salience ADD COLUMN encoding_source TEXT DEFAULT NULL;
+    `,
+    },
 ];
 /**
  * Apply every pending migration in a single transaction per migration.

package/dist/scripts/migrate-storage.js

@@ -9978,6 +9978,12 @@ var init_state_db = __esm(() => {
       CREATE INDEX IF NOT EXISTS idx_recombine_hypotheses_last_seen
         ON recombine_hypotheses(last_seen_at);
     `
+    },
+    {
+      id: "015-asset-salience-encoding-source",
+      up: `
+      ALTER TABLE asset_salience ADD COLUMN encoding_source TEXT DEFAULT NULL;
+    `
     }
   ];
 });

package/dist/scripts/migrations/import-fs-improve-runs-to-db.js

@@ -9108,6 +9108,12 @@ var MIGRATIONS = [
       CREATE INDEX IF NOT EXISTS idx_recombine_hypotheses_last_seen
         ON recombine_hypotheses(last_seen_at);
     `
+  },
+  {
+    id: "015-asset-salience-encoding-source",
+    up: `
+      ALTER TABLE asset_salience ADD COLUMN encoding_source TEXT DEFAULT NULL;
+    `
   }
 ];
 function runMigrations2(db) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.36",
+  "version": "0.9.0-beta.38",
   "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": [