akm-cli 0.9.0-beta.37 → 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/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/package.json

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