akm-cli 0.9.0-rc.2 → 0.9.0-rc.3

package/dist/commands/improve/procedural.js

@@ -21,13 +21,14 @@
  */
 import { createHash } from "node:crypto";
 import fs from "node:fs";
+import path from "node:path";
 import proceduralSystemPrompt from "../../assets/prompts/procedural-system.md" with { type: "text" };
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { appendEvent } from "../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
-import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
+import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { closeDatabase, getAllEntries, openExistingDatabase } from "../../indexer/db/db.js";
 import { parseWorkflow } from "../../workflows/parser.js";
 import { createProposal, isProposalSkipped } from "../proposal/repository.js";
@@ -212,10 +213,11 @@ function kebab(s) {
         .replace(/^-|-$/g, "") || "step");
 }
 /** Build the exact workflow markdown the parser accepts. */
-export function assembleWorkflowMarkdown(doc) {
+export function assembleWorkflowMarkdown(doc, xrefs = []) {
     const lines = [
         "---",
         `description: ${JSON.stringify(doc.description)}`,
+        ...(xrefs.length > 0 ? ["xrefs:", ...xrefs.map((ref) => `  - ${ref}`)] : []),
         "---",
         "",
         `# Workflow: ${doc.title}`,
@@ -268,7 +270,8 @@ export async function akmProcedural(opts) {
     let db;
     try {
         db = openExistingDatabase();
-        entries = getAllEntries(db);
+        const selectedRoot = path.resolve(stashDir);
+        entries = getAllEntries(db).filter((entry) => path.resolve(entry.stashDir) === selectedRoot);
     }
     catch (e) {
         warnings.push(`procedural: failed to open index — ${String(e)}`);
@@ -301,7 +304,7 @@ export async function akmProcedural(opts) {
     }
     // Procedural output is a workflow (non-wiki) → stash authoring standards.
     // Resolved ONCE per run and passed to each sequence prompt.
-    const standardsContext = resolveStashStandards(stashDir);
+    const standardsContext = resolveStandardsContext("workflow:_procedural", stashDir);
     for (const cluster of clusters) {
         if (opts.signal?.aborted) {
             warnings.push("aborted-mid-run");
@@ -345,7 +348,8 @@ export async function akmProcedural(opts) {
         }
         // Assemble + locally validate the workflow markdown. Never queue an
         // unparseable workflow.
-        const content = assembleWorkflowMarkdown(doc);
+        const xrefs = cluster.members.map((member) => member.ref).sort();
+        const content = assembleWorkflowMarkdown(doc, xrefs);
         const parsed = parseWorkflow(content, { path: workflowRef });
         if (!parsed.ok) {
             appendEvent({
@@ -365,7 +369,7 @@ export async function akmProcedural(opts) {
             ref: workflowRef,
             source: "procedural",
             sourceRun,
-            payload: { content, frontmatter: { description: doc.description } },
+            payload: { content, frontmatter: { description: doc.description, xrefs } },
             eligibilitySource,
         }, opts.ctx);
         if (isProposalSkipped(proposalResult)) {

package/dist/commands/improve/recombine.js

@@ -25,8 +25,9 @@
  * not re-promoted on every subsequent run. Hypotheses NOT re-induced in a run
  * have their consecutive streak reset (decay-to-zero).
  *
- * NAMESPACE note: the ref stays `lesson:recombined/<slug>-<hash>` for BOTH
- * passes. The ref is the promotion TARGET asset (a lesson in both the hypothesis
+ * NAMESPACE note: the ref stays stable for BOTH passes. A unanimous source-memory
+ * scope is preserved; unscoped members produce a flat lesson ref rather than an
+ * invented type scope. The ref is the promotion TARGET asset (a lesson in both the hypothesis
  * and promoted states), so re-induction must map to the same ref and the ref
  * cannot encode the proposal type. The hypothesis-vs-lesson distinction is
  * carried ONLY by the proposal frontmatter `type` field. On promotion the prior
@@ -39,6 +40,7 @@
  */
 import { createHash } from "node:crypto";
 import fs from "node:fs";
+import path from "node:path";
 import recombineSystemPrompt from "../../assets/prompts/recombine-system.md" with { type: "text" };
 import { assembleAssetFromString } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
@@ -46,7 +48,7 @@ import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { appendEvent } from "../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
-import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
+import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { withStateDbAsync } from "../../core/state-db.js";
 import { closeDatabase, getAllEntries, getEntitiesByEntryIds, openExistingDatabase, } from "../../indexer/db/db.js";
 import { decayUnseenRecombineHypotheses, findMatchingRecombineHypothesis, getRecombineHypothesis, markRecombineHypothesisPromoted, recordRecombineInduction, } from "../../storage/repositories/recombine-repository.js";
@@ -427,7 +429,24 @@ export function deriveRecombineLessonRef(cluster) {
         .replace(/^-|-$/g, "");
     const memberKey = recombineMemberKey(cluster);
     const hash = createHash("sha256").update(memberKey, "utf8").digest("hex").slice(0, 8);
-    return `lesson:recombined/${slug || "cluster"}-${hash}`;
+    const scopeResult = recombineClusterScope(cluster);
+    if (!scopeResult.ok)
+        throw new Error("Cannot derive a lesson ref for a cluster with mixed scopes.");
+    return `lesson:${scopeResult.scope ? `${scopeResult.scope}/` : ""}${slug || "cluster"}-${hash}`;
+}
+function recombineClusterScope(cluster) {
+    const scopes = new Set(cluster.members.map((member) => {
+        const parts = member.entry.name.split("/");
+        return parts.length > 1 ? parts[0] : "";
+    }));
+    if (scopes.size !== 1)
+        return { ok: false };
+    const scope = [...scopes][0]
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return { ok: true, scope };
 }
 function validatePromotedLessonFrontmatter(ref, frontmatter) {
     const descCheck = isValidDescription(frontmatter.description, ref);
@@ -511,7 +530,8 @@ export async function akmRecombine(opts) {
     let db;
     try {
         db = openExistingDatabase();
-        entries = getAllEntries(db, "memory");
+        const selectedRoot = path.resolve(stashDir);
+        entries = getAllEntries(db, "memory").filter((entry) => path.resolve(entry.stashDir) === selectedRoot);
         if (relatednessSource === "graph" || relatednessSource === "both") {
             try {
                 entityByEntryId = getEntitiesByEntryIds(db, entries.map((e) => e.id));
@@ -565,7 +585,7 @@ export async function akmRecombine(opts) {
     const seenThisRun = new Set();
     // Recombine output is knowledge/lesson (non-wiki) → stash authoring
     // standards. Resolved ONCE per run and passed to each cluster prompt.
-    const standardsContext = resolveStashStandards(stashDir);
+    const standardsContext = resolveStandardsContext("lesson:_recombined", stashDir);
     // #625 — open the confirmation-count store once per run via the ctx seam,
     // reusing a long-lived ctx.db handle when the caller provided one (mirrors
     // proposals.ts). Only handles WE opened are closed by the seam.
@@ -576,6 +596,10 @@ export async function akmRecombine(opts) {
                 break;
             }
             clustersFormed += 1;
+            if (!recombineClusterScope(cluster).ok) {
+                warnings.push(`recombine: skipped ${cluster.signature} cluster with mixed scopes`);
+                continue;
+            }
             // #9 — promotion is terminal. If this cluster Jaccard-matches a
             // hypothesis that was ALREADY promoted, generating again can at best
             // re-queue a redundant `type: hypothesis` for a settled ref (promotion
@@ -709,7 +733,7 @@ export async function akmRecombine(opts) {
                 type: proposalType,
                 description: generalization.description,
                 ...(generalization.when_to_use ? { when_to_use: generalization.when_to_use } : {}),
-                source_refs: sourceRefs,
+                xrefs: sourceRefs,
             };
             const content = assembleContent(frontmatter, generalization.body);
             if (promote && stateDb) {

package/dist/commands/improve/reflect.js

@@ -46,7 +46,9 @@ import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/
 import { createProposal, isProposalSkipped, listProposals, } from "../proposal/repository.js";
 import { checkReflectSize, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
 import { deriveLessonRef, runLessonQualityJudge } from "./distill.js";
+import { findAssetFilePath } from "./eligibility.js";
 import { classifyReflectChange } from "./reflect-noise.js";
+import { bareImproveRef, durableImproveRef } from "./source-identity.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 /**
@@ -55,12 +57,13 @@ const MAX_GLOBAL_FEEDBACK_LINES = 20;
  * all assets so `akm reflect` can operate in a general "review recent
  * signals" mode. Best-effort — a missing or empty events stream returns `[]`.
  */
-function readRecentFeedback(ref) {
+function readRecentFeedback(ref, legacyRef) {
     try {
-        const result = readEvents({ type: "feedback", ...(ref ? { ref } : {}) });
+        const result = readEvents({ type: "feedback", ...(ref && !legacyRef ? { ref } : {}) });
+        const events = ref && legacyRef ? result.events.filter((event) => event.ref === ref || event.ref === legacyRef) : result.events;
         const lines = [];
         const limit = ref ? MAX_FEEDBACK_LINES : MAX_GLOBAL_FEEDBACK_LINES;
-        for (const event of result.events.slice(-limit)) {
+        for (const event of events.slice(-limit)) {
             const md = (event.metadata ?? {});
             const signal = typeof md.signal === "string" ? md.signal : "?";
             const note = typeof md.reason === "string" ? md.reason : typeof md.note === "string" ? md.note : "";
@@ -187,7 +190,7 @@ function hasRelatedSkillSource(content, skillRef) {
     const sources = parsed.data.sources;
     return Array.isArray(sources) && sources.some((source) => typeof source === "string" && source.trim() === skillRef);
 }
-async function readRelatedLessons(stash, ref, parsedRef) {
+async function readRelatedLessons(stash, ref, parsedRef, sourceName) {
     if (parsedRef.type !== "skill")
         return [];
     const related = new Map();
@@ -198,7 +201,7 @@ async function readRelatedLessons(stash, ref, parsedRef) {
         related.set(derivedLessonRef, { ref: derivedLessonRef, content: fs.readFileSync(derivedLessonPath, "utf8") });
     }
     try {
-        const feedbackEvents = readEvents({ type: "distill_invoked", ref }).events;
+        const feedbackEvents = readEvents({ type: "distill_invoked", ref: durableImproveRef(ref, sourceName) }).events;
         for (const event of feedbackEvents) {
             const lessonRef = typeof event.metadata?.lessonRef === "string" ? event.metadata.lessonRef : undefined;
             if (lessonRef?.startsWith("lesson:"))
@@ -210,10 +213,10 @@ async function readRelatedLessons(stash, ref, parsedRef) {
     }
     for (const candidateRef of candidateRefs) {
         try {
-            const entry = await lookup(parseAssetRef(candidateRef));
-            if (!entry?.filePath || !fs.existsSync(entry.filePath))
+            const filePath = await findAssetFilePath(durableImproveRef(candidateRef, sourceName), stash);
+            if (!filePath || !fs.existsSync(filePath))
                 continue;
-            const content = fs.readFileSync(entry.filePath, "utf8");
+            const content = fs.readFileSync(filePath, "utf8");
             related.set(candidateRef, { ref: candidateRef, content });
         }
         catch {
@@ -698,7 +701,7 @@ export async function akmReflect(options = {}) {
     // attempt regardless of downstream success/failure.
     appendEvent({
         eventType: "reflect_invoked",
-        ...(options.ref ? { ref: options.ref } : {}),
+        ...(options.ref ? { ref: durableImproveRef(options.ref, options.sourceName) } : {}),
         metadata: {
             ...(options.task ? { task: options.task } : {}),
             ...(options.engine ? { engine: options.engine } : {}),
@@ -760,9 +763,16 @@ export async function akmReflect(options = {}) {
         }
         else {
             try {
-                const entry = await lookup(parsedRef);
-                if (entry?.filePath && fs.existsSync(entry.filePath)) {
-                    assetContent = fs.readFileSync(entry.filePath, "utf8");
+                const qualifiedRef = durableImproveRef(options.ref, options.sourceName);
+                const localFilePath = await findAssetFilePath(qualifiedRef, stash);
+                if (localFilePath && fs.existsSync(localFilePath)) {
+                    assetContent = fs.readFileSync(localFilePath, "utf8");
+                }
+                else {
+                    const entry = await lookup(parseAssetRef(qualifiedRef));
+                    if (entry?.filePath && fs.existsSync(entry.filePath)) {
+                        assetContent = fs.readFileSync(entry.filePath, "utf8");
+                    }
                 }
             }
             catch {
@@ -809,9 +819,9 @@ export async function akmReflect(options = {}) {
     // 4. Build the shared prompt inputs — feedback, hints, lessons, rejected
     // proposals. These are stable across refinement iterations; only the
     // `priorDraft` field changes per-iteration (R-1 / #372).
-    const feedback = readRecentFeedback(options.ref);
+    const feedback = readRecentFeedback(options.ref ? durableImproveRef(options.ref, options.sourceName) : undefined, options.ref && options.legacyBareState ? bareImproveRef(options.ref) : undefined);
     const schemaHints = buildSchemaHints(parsedRef?.type ?? "", assetContent);
-    const relatedLessons = options.ref && parsedRef ? await readRelatedLessons(stash, options.ref, parsedRef) : [];
+    const relatedLessons = options.ref && parsedRef ? await readRelatedLessons(stash, options.ref, parsedRef, options.sourceName) : [];
     // Reflexion-style verbal-RL: inject rejected proposals so the agent avoids
     // reproducing proposals that have already been reviewed and refused.
     const rejectedProposals = readRejectedProposals(stash, options.ref);

package/dist/commands/improve/salience.js

@@ -45,6 +45,7 @@
  *
  * @module salience
  */
+import path from "node:path";
 import { makeAssetRef } from "../../core/asset/asset-ref.js";
 import { getAllEntries, getUtilityScoresByIds } from "../../indexer/db/db.js";
 import { WARM_START_CAP } from "./outcome-loop.js";
@@ -424,14 +425,17 @@ export function buildRankChangeReport(oldRanks, newRanks, oldTopN = 200, forgett
  * @param indexDb - An open read-capable index database connection.
  * @param refs    - The set of asset refs to look up.
  */
-export function getLastUseMsByRef(indexDb, refs) {
+export function getLastUseMsByRef(indexDb, refs, stashDir) {
     const result = new Map();
     if (refs.length === 0)
         return result;
     const refSet = new Set(refs);
     const allEntries = getAllEntries(indexDb);
+    const selectedRoot = stashDir ? path.resolve(stashDir) : undefined;
     const idToRef = new Map();
     for (const indexed of allEntries) {
+        if (selectedRoot && path.resolve(indexed.stashDir) !== selectedRoot)
+            continue;
         const ref = makeAssetRef(indexed.entry.type, indexed.entry.name);
         if (refSet.has(ref))
             idToRef.set(indexed.id, ref);

package/dist/commands/improve/source-identity.js

@@ -0,0 +1,43 @@
+// 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/.
+import path from "node:path";
+import { parseAssetRef, refToString } from "../../core/asset/asset-ref.js";
+/** Key durable improve state by source without changing filesystem-facing refs. */
+export function durableImproveRef(ref, sourceName) {
+    if (!sourceName)
+        return ref;
+    const parsed = parseAssetRef(ref);
+    return refToString({ ...parsed, origin: parsed.origin ?? sourceName });
+}
+/** Remove a durable source origin before filesystem/index lookups. */
+export function bareImproveRef(ref) {
+    const parsed = parseAssetRef(ref);
+    return refToString({ type: parsed.type, name: parsed.name });
+}
+/** Qualified key first, with the pre-cutover bare key as an optional fallback. */
+export function improveStateReadRefs(ref, sourceName, includeLegacyBare = false) {
+    const durable = durableImproveRef(ref, sourceName);
+    const bare = bareImproveRef(ref);
+    return includeLegacyBare && durable !== bare ? [durable, bare] : [durable];
+}
+/**
+ * Bare improve state predates source-qualified refs and belongs only to the
+ * historical local stash. Named sources at any other root must never inherit it.
+ */
+export function shouldReadLegacyBareImproveState(sourceName, sourcePath, config) {
+    if (!sourceName || !sourcePath)
+        return false;
+    if (config.stashDir)
+        return path.resolve(sourcePath) === path.resolve(config.stashDir);
+    if (sourceName !== "stash")
+        return false;
+    if (!config.defaultWriteTarget)
+        return true;
+    if (config.defaultWriteTarget !== "stash")
+        return false;
+    const configuredStash = config.sources?.find((source) => source.name === "stash");
+    return (configuredStash?.type === "filesystem" &&
+        typeof configuredStash.path === "string" &&
+        path.resolve(configuredStash.path) === path.resolve(sourcePath));
+}

package/dist/commands/migrate-cli.js

@@ -0,0 +1,36 @@
+// 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/.
+import { defineGroupCommand, defineJsonCommand } from "../cli/shared.js";
+import { UsageError } from "../core/errors.js";
+const configArg = {
+    type: "string",
+    description: "Complete operator-prepared current config; optional when the active config is current",
+};
+export const migrateCommand = defineGroupCommand({
+    meta: { name: "migrate", description: "Inspect or apply config and durable database migrations" },
+    subCommands: {
+        status: defineJsonCommand({
+            meta: { name: "status", description: "Read-only cross-artifact migration eligibility check" },
+            args: { config: configArg },
+            async run({ args }) {
+                const { runMigrationStatus } = await import("../cli/config-migrate.js");
+                await runMigrationStatus({ preparedConfigPath: args.config });
+            },
+        }),
+        apply: defineJsonCommand({
+            meta: { name: "apply", description: "Create a verified backup and atomically apply pending migrations" },
+            args: {
+                config: configArg,
+                dryRun: { type: "boolean", default: false, description: "Run the same eligibility checks without mutation" },
+            },
+            async run({ args }) {
+                const { runMigrationApply } = await import("../cli/config-migrate.js");
+                await runMigrationApply({ preparedConfigPath: args.config, dryRun: args.dryRun });
+            },
+        }),
+    },
+    defaultRun() {
+        throw new UsageError("Choose `migrate status` or `migrate apply`.", "MISSING_REQUIRED_ARGUMENT");
+    },
+});