akm-cli 0.9.2-alpha.2 → 0.9.2-alpha.3

package/CHANGELOG.md

@@ -6,9 +6,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.2-alpha.3] - 2026-08-26
+
+### Fixed
+
+- **Currency in prose no longer retypes an asset as a command** (#824). The
+  smart-Markdown classifier matched `$1`/`$2`/`$3` with a trailing word
+  boundary, and that boundary sits between the `2` and the comma in `$2,000` —
+  so any note quoting a price was indexed as a `command`, its ref moved to
+  `commands/<dir>/<slug>`, and it left its own namespace. Measured on a real
+  corpus, 3 of 51 memory documents were affected, and those 3 were exactly the
+  3 whose bodies matched. `$ARGUMENTS` is unambiguous and keeps its existing
+  precedence over a directory hint; the numeric placeholders now exclude a
+  following digit (or a `.`/`,` followed by one), and where they still
+  disagree with a directory that declares a type, the declaration wins. The
+  defect is present identically in 0.9.1 — it only became visible once the
+  0.9.2-alpha.2 retrieval work let mistyped assets surface in results.
+
+### Documentation
+
+- Recorded the 0.9.2 retrieval measurement in
+  `docs/plans/benchmark-tuning-findings.md` §2e (#825). Retrieval-only probes
+  with no model in the loop, identical corpora, only the CLI version differing:
+  LoCoMo zero-hit 75.0% -> 0.0% and evidence recall@5 0.154 -> 0.590;
+  LongMemEval zero-hit 100% -> 0.0% and recall@5 0.000 -> 1.000.
+
 ## [0.9.2-alpha.2] - 2026-08-25
 
-- TODO
+### Fixed
+
+- **Retrieval:** relaxed zero-hit lexical queries centrally, stabilized
+  relaxed-retrieval quality, and preserved name quality through relaxed
+  ranking. This is the change measured in §2e above — it is what lifted the
+  retrieval ceiling that had floored memory-backed evaluation.
+- **Indexing:** verify vec completeness before promotion; compare vec IDs as
+  exact sets; materialize vectors for targeted writes; make nested entry
+  mutation atomic; reconcile clean before final verification; restore static
+  embedding imports.
+- **Markdown projection:** parse nested links safely, parse destination
+  phases, and project with stateful delimiters.
+- **Sources:** reconcile local bundle updates and report incomplete filesystem
+  reconciliation.
+- **Extract:** keep malformed model output retryable.
+
+### Performance
+
+- Keep targeted embedding selection narrow and preserve targeted vec
+  degradation.
 
 ## [0.9.2-alpha.1] - 2026-08-24
 

package/dist/indexer/walk/matchers.js

@@ -101,7 +101,21 @@ const DIR_TYPE_MAP = [
         test: (ext) => ext === ".md",
     },
 ];
-const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
+/**
+ * `$ARGUMENTS` — unambiguous. Nothing else writes it, so finding it in a body
+ * is strong evidence of a command wherever the file lives.
+ */
+const ARGUMENTS_PLACEHOLDER_RE = /\$ARGUMENTS/;
+/**
+ * `$1` / `$2` / `$3` — AMBIGUOUS, because ordinary prose writes money the same
+ * way. The old combined pattern used `\$[123]\b`, and `\b` sits between the
+ * `2` and the comma in `$2,000`, so every note quoting a price read as a
+ * command (#824). Excluding a following digit, or a `.`/`,` that is itself
+ * followed by a digit, rules out `$1,200` / `$2,000` / `$2.50` / `$12` while
+ * still matching `$1.` at the end of a sentence — a period with no digit after
+ * it is not part of a number.
+ */
+const NUMERIC_PLACEHOLDER_RE = /\$[123](?!\d|[.,]\d)/;
 const SMART_MD_FACTS = {
     workflow: { type: "workflow", specificity: 19 },
     toolsAgent: { type: "agent", specificity: 20 },
@@ -141,6 +155,17 @@ function matchDirectoryHint(dirName, ctx, specificity) {
     }
     return null;
 }
+/**
+ * True when some ancestor directory already DECLARES this file's type via
+ * `DIR_TYPE_MAP` — the same walk `classifyByDirectory` performs. Derived from
+ * path fields alone, so `smartMdPathCandidates` can apply it without reading
+ * bytes.
+ */
+function hasDeclaredDirType(ctx) {
+    if (isNestedSkillResource(ctx))
+        return false;
+    return ctx.ancestorDirs.some((dir) => matchDirectoryHint(dir, ctx, 0) !== null);
+}
 function classifyByExtension(ctx) {
     if (ctx.fileName === "SKILL.md") {
         return { type: "skill", specificity: 25 };
@@ -204,7 +229,19 @@ function classifyBySmartMd(ctx) {
             return SMART_MD_FACTS.command;
         }
     }
-    if (COMMAND_PLACEHOLDER_RE.test(body)) {
+    // `$ARGUMENTS` is unambiguous, so it keeps its long-standing precedence: a
+    // command dropped under `knowledge/` is still found as a command.
+    if (ARGUMENTS_PLACEHOLDER_RE.test(body)) {
+        return SMART_MD_FACTS.command;
+    }
+    // A NUMERIC placeholder is a guess, and a typed directory is a declaration.
+    // Where the two disagree the declaration wins — otherwise a note that merely
+    // quotes a price is retyped, which is #824: `memories/*.md` mentioning
+    // `$2,000` were indexed as commands, their refs moved to
+    // `commands/memories/<slug>`, and they left the `memories/` namespace
+    // entirely. Outside a typed directory there is no declaration to defer to,
+    // so the guess still stands.
+    if (NUMERIC_PLACEHOLDER_RE.test(body) && !hasDeclaredDirType(ctx)) {
         return SMART_MD_FACTS.command;
     }
     if (fm && "model" in fm) {

package/dist/scripts/akm-migrate-node.js

@@ -14421,7 +14421,8 @@ var DIR_TYPE_MAP = [
     test: (ext) => ext === ".md"
   }
 ];
-var COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
+var ARGUMENTS_PLACEHOLDER_RE = /\$ARGUMENTS/;
+var NUMERIC_PLACEHOLDER_RE = /\$[123](?!\d|[.,]\d)/;
 var SMART_MD_FACTS = {
   workflow: { type: "workflow", specificity: 19 },
   toolsAgent: { type: "agent", specificity: 20 },
@@ -14449,6 +14450,11 @@ function matchDirectoryHint(dirName, ctx, specificity) {
   }
   return null;
 }
+function hasDeclaredDirType(ctx) {
+  if (isNestedSkillResource(ctx))
+    return false;
+  return ctx.ancestorDirs.some((dir) => matchDirectoryHint(dir, ctx, 0) !== null);
+}
 function classifyByExtension(ctx) {
   if (ctx.fileName === "SKILL.md") {
     return { type: "skill", specificity: 25 };
@@ -14498,7 +14504,10 @@ function classifyBySmartMd(ctx) {
       return SMART_MD_FACTS.command;
     }
   }
-  if (COMMAND_PLACEHOLDER_RE.test(body)) {
+  if (ARGUMENTS_PLACEHOLDER_RE.test(body)) {
+    return SMART_MD_FACTS.command;
+  }
+  if (NUMERIC_PLACEHOLDER_RE.test(body) && !hasDeclaredDirType(ctx)) {
     return SMART_MD_FACTS.command;
   }
   if (fm && "model" in fm) {

package/dist/scripts/akm-migrate.js

@@ -14352,7 +14352,8 @@ var DIR_TYPE_MAP = [
     test: (ext) => ext === ".md"
   }
 ];
-var COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
+var ARGUMENTS_PLACEHOLDER_RE = /\$ARGUMENTS/;
+var NUMERIC_PLACEHOLDER_RE = /\$[123](?!\d|[.,]\d)/;
 var SMART_MD_FACTS = {
   workflow: { type: "workflow", specificity: 19 },
   toolsAgent: { type: "agent", specificity: 20 },
@@ -14380,6 +14381,11 @@ function matchDirectoryHint(dirName, ctx, specificity) {
   }
   return null;
 }
+function hasDeclaredDirType(ctx) {
+  if (isNestedSkillResource(ctx))
+    return false;
+  return ctx.ancestorDirs.some((dir) => matchDirectoryHint(dir, ctx, 0) !== null);
+}
 function classifyByExtension(ctx) {
   if (ctx.fileName === "SKILL.md") {
     return { type: "skill", specificity: 25 };
@@ -14429,7 +14435,10 @@ function classifyBySmartMd(ctx) {
       return SMART_MD_FACTS.command;
     }
   }
-  if (COMMAND_PLACEHOLDER_RE.test(body)) {
+  if (ARGUMENTS_PLACEHOLDER_RE.test(body)) {
+    return SMART_MD_FACTS.command;
+  }
+  if (NUMERIC_PLACEHOLDER_RE.test(body) && !hasDeclaredDirType(ctx)) {
     return SMART_MD_FACTS.command;
   }
   if (fm && "model" in fm) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.2-alpha.2",
+  "version": "0.9.2-alpha.3",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [