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

package/dist/commands/improve/distill-promotion-policy.js

@@ -44,7 +44,13 @@ function deriveDescription(body, description) {
 }
 export function deriveKnowledgeRef(inputRef) {
     const parsed = parseAssetRef(inputRef);
-    return `knowledge:${parsed.name}`;
+    const leaf = parsed.name.split("/").filter(Boolean).at(-1) ?? parsed.name;
+    const safe = leaf
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return `knowledge:${safe}`;
 }
 function collectPromotionFeatures(input) {
     const parsed = parseAssetRef(input.inputRef);
@@ -112,14 +118,14 @@ function buildKnowledgeContent(input) {
     const body = parsedContent.content.trim();
     const description = typeof fm.description === "string" ? fm.description.trim() : undefined;
     const normalizedDescription = deriveDescription(body, description);
-    const sources = [input.inputRef];
+    const xrefs = [input.inputRef];
     if (typeof fm.source === "string" && fm.source.trim())
-        sources.push(fm.source.trim());
+        xrefs.push(fm.source.trim());
     const knowledgeFrontmatter = {
         ...(normalizedDescription ? { description: normalizedDescription } : {}),
         ...(Array.isArray(fm.tags) ? { tags: fm.tags } : {}),
         ...(typeof fm.observed_at === "string" && fm.observed_at.trim() ? { observed_at: fm.observed_at.trim() } : {}),
-        sources,
+        xrefs,
     };
     return assembleAsset(knowledgeFrontmatter, body);
 }
@@ -517,7 +523,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                     score: 4.250000000000001,
                     threshold: 3.8,
                     knowledgeRef: "knowledge:deploy-vpn-required",
-                    content: "---\ndescription: VPN required before deploy\ntags:\n  - deploy\n  - ops\nobserved_at: 2026-04-20\nsources:\n  - memory:deploy-vpn-required\n  - skill:deploy\n---\n\nAlways connect the VPN before starting production deploys.\n",
+                    content: "---\ndescription: VPN required before deploy\ntags:\n  - deploy\n  - ops\nobserved_at: 2026-04-20\nxrefs:\n  - memory:deploy-vpn-required\n  - skill:deploy\n---\n\nAlways connect the VPN before starting production deploys.\n",
                     blockedBy: [],
                     positiveSignals: [
                         "2 positive feedback events",
@@ -543,7 +549,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                     score: 5.240000000000002,
                     threshold: 3.8,
                     knowledgeRef: "knowledge:release-smoke-test",
-                    content: "---\ndescription: Smoke test gates release\nobserved_at: 2026-04-18\nsources:\n  - memory:release-smoke-test\n  - skill:release\n---\n\nRun the smoke test before tagging a release candidate.\n",
+                    content: "---\ndescription: Smoke test gates release\nobserved_at: 2026-04-18\nxrefs:\n  - memory:release-smoke-test\n  - skill:release\n---\n\nRun the smoke test before tagging a release candidate.\n",
                     blockedBy: [],
                     positiveSignals: [
                         "3 positive feedback events",
@@ -569,7 +575,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                     score: 4.250000000000001,
                     threshold: 3.8,
                     knowledgeRef: "knowledge:kubernetes-rollout-check",
-                    content: "---\ndescription: Verify rollout status after apply\ntags:\n  - k8s\nobserved_at: 2026-04-15\nsources:\n  - memory:kubernetes-rollout-check\n  - skill:k8s\n---\n\nCheck rollout status after kubectl apply before declaring success.\n",
+                    content: "---\ndescription: Verify rollout status after apply\ntags:\n  - k8s\nobserved_at: 2026-04-15\nxrefs:\n  - memory:kubernetes-rollout-check\n  - skill:k8s\n---\n\nCheck rollout status after kubectl apply before declaring success.\n",
                     blockedBy: [],
                     positiveSignals: [
                         "2 positive feedback events",
@@ -595,7 +601,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                     score: 5.450000000000002,
                     threshold: 3.8,
                     knowledgeRef: "knowledge:incident-channel-rule",
-                    content: "---\ndescription: Incident bridge stays single-threaded\nobserved_at: 2026-04-12\nsources:\n  - memory:incident-channel-rule\n  - skill:incident\n---\n\nKeep one operator narrating decisions in the incident bridge to avoid conflicting instructions.\n",
+                    content: "---\ndescription: Incident bridge stays single-threaded\nobserved_at: 2026-04-12\nxrefs:\n  - memory:incident-channel-rule\n  - skill:incident\n---\n\nKeep one operator narrating decisions in the incident bridge to avoid conflicting instructions.\n",
                     blockedBy: [],
                     positiveSignals: [
                         "3 positive feedback events",
@@ -710,7 +716,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                     score: 4.1000000000000005,
                     threshold: 3.8,
                     knowledgeRef: "knowledge:feedback-conflict",
-                    content: "---\ndescription: VPN required before deploy\nobserved_at: 2026-04-20\nsources:\n  - memory:feedback-conflict\n  - skill:deploy\n---\n\nAlways connect the VPN before starting production deploys.\n",
+                    content: "---\ndescription: VPN required before deploy\nobserved_at: 2026-04-20\nxrefs:\n  - memory:feedback-conflict\n  - skill:deploy\n---\n\nAlways connect the VPN before starting production deploys.\n",
                     blockedBy: [],
                     positiveSignals: [
                         "2 positive feedback events",
@@ -758,7 +764,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                     score: 4.840000000000001,
                     threshold: 3.8,
                     knowledgeRef: "knowledge:staging-cutover-order",
-                    content: "---\ndescription: Cut over staging after migrations\ntags:\n  - db\n  - deploy\nobserved_at: 2026-04-10\nsources:\n  - memory:staging-cutover-order\n  - skill:database\n---\n\nRun database migrations before shifting staging traffic onto the new release.\n",
+                    content: "---\ndescription: Cut over staging after migrations\ntags:\n  - db\n  - deploy\nobserved_at: 2026-04-10\nxrefs:\n  - memory:staging-cutover-order\n  - skill:database\n---\n\nRun database migrations before shifting staging traffic onto the new release.\n",
                     blockedBy: [],
                     positiveSignals: [
                         "3 positive feedback events",
@@ -855,7 +861,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                     score: 5.600000000000002,
                     threshold: 3.8,
                     knowledgeRef: "knowledge:kafka-rebalance-note",
-                    content: "---\ndescription: Pause consumers during rebalance\ntags:\n  - kafka\n  - ops\nobserved_at: 2026-04-08\nsources:\n  - memory:kafka-rebalance-note\n  - skill:kafka\n---\n\nPause consumers during partition rebalances to avoid duplicate processing while assignments settle.\n",
+                    content: "---\ndescription: Pause consumers during rebalance\ntags:\n  - kafka\n  - ops\nobserved_at: 2026-04-08\nxrefs:\n  - memory:kafka-rebalance-note\n  - skill:kafka\n---\n\nPause consumers during partition rebalances to avoid duplicate processing while assignments settle.\n",
                     blockedBy: [],
                     positiveSignals: [
                         "3 positive feedback events",
@@ -882,7 +888,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                     score: 4.04,
                     threshold: 3.8,
                     knowledgeRef: "knowledge:gha-token-scope",
-                    content: "---\ndescription: Minimize GitHub token scopes\ntags:\n  - gha\n  - security\nobserved_at: 2026-04-07\nsources:\n  - memory:gha-token-scope\n  - skill:github-actions\n---\n\nUse the narrowest GitHub token scope that still allows the workflow step to succeed.\n",
+                    content: "---\ndescription: Minimize GitHub token scopes\ntags:\n  - gha\n  - security\nobserved_at: 2026-04-07\nxrefs:\n  - memory:gha-token-scope\n  - skill:github-actions\n---\n\nUse the narrowest GitHub token scope that still allows the workflow step to succeed.\n",
                     blockedBy: [],
                     positiveSignals: [
                         "2 positive feedback events",
@@ -932,7 +938,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                     score: 5.600000000000002,
                     threshold: 3.8,
                     knowledgeRef: "knowledge:terraform-state-location",
-                    content: "---\ndescription: Use remote state locks\ntags:\n  - terraform\nobserved_at: 2026-04-04\nsources:\n  - memory:terraform-state-location\n  - skill:terraform\n---\n\nUse remote state with locking enabled before applying shared Terraform stacks.\n",
+                    content: "---\ndescription: Use remote state locks\ntags:\n  - terraform\nobserved_at: 2026-04-04\nxrefs:\n  - memory:terraform-state-location\n  - skill:terraform\n---\n\nUse remote state with locking enabled before applying shared Terraform stacks.\n",
                     blockedBy: [],
                     positiveSignals: [
                         "3 positive feedback events",
@@ -984,7 +990,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                     score: 4.250000000000001,
                     threshold: 3.8,
                     knowledgeRef: "knowledge:cache-ttl-fact",
-                    content: "---\ndescription: Cache TTL defaults to five minutes\ntags:\n  - cache\n  - platform\nobserved_at: 2026-04-02\nsources:\n  - memory:cache-ttl-fact\n  - skill:platform\n---\n\nThe shared platform cache TTL defaults to five minutes unless the service opts out.\n",
+                    content: "---\ndescription: Cache TTL defaults to five minutes\ntags:\n  - cache\n  - platform\nobserved_at: 2026-04-02\nxrefs:\n  - memory:cache-ttl-fact\n  - skill:platform\n---\n\nThe shared platform cache TTL defaults to five minutes unless the service opts out.\n",
                     blockedBy: [],
                     positiveSignals: [
                         "2 positive feedback events",
@@ -1046,7 +1052,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 3,
                             threshold: 2,
                             knowledgeRef: "knowledge:kafka-rebalance-note",
-                            content: "---\ndescription: Pause consumers during rebalance\ntags:\n  - kafka\n  - ops\nobserved_at: 2026-04-08\nsources:\n  - memory:kafka-rebalance-note\n  - skill:kafka\n---\n\nPause consumers during partition rebalances to avoid duplicate processing while assignments settle.\n",
+                            content: "---\ndescription: Pause consumers during rebalance\ntags:\n  - kafka\n  - ops\nobserved_at: 2026-04-08\nxrefs:\n  - memory:kafka-rebalance-note\n  - skill:kafka\n---\n\nPause consumers during partition rebalances to avoid duplicate processing while assignments settle.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline positive feedback rule"],
                             negativeSignals: [],
@@ -1063,7 +1069,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 2,
                             threshold: 2,
                             knowledgeRef: "knowledge:gha-token-scope",
-                            content: "---\ndescription: Minimize GitHub token scopes\ntags:\n  - gha\n  - security\nobserved_at: 2026-04-07\nsources:\n  - memory:gha-token-scope\n  - skill:github-actions\n---\n\nUse the narrowest GitHub token scope that still allows the workflow step to succeed.\n",
+                            content: "---\ndescription: Minimize GitHub token scopes\ntags:\n  - gha\n  - security\nobserved_at: 2026-04-07\nxrefs:\n  - memory:gha-token-scope\n  - skill:github-actions\n---\n\nUse the narrowest GitHub token scope that still allows the workflow step to succeed.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline positive feedback rule"],
                             negativeSignals: [],
@@ -1080,7 +1086,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 2,
                             threshold: 2,
                             knowledgeRef: "knowledge:helm-debug-guess",
-                            content: "---\ndescription: Helm upgrade might need --debug\nobserved_at: 2026-04-05\nsources:\n  - memory:helm-debug-guess\n  - skill:helm\n---\n\nIt might help to add --debug to helm upgrade output during failures.\n",
+                            content: "---\ndescription: Helm upgrade might need --debug\nobserved_at: 2026-04-05\nxrefs:\n  - memory:helm-debug-guess\n  - skill:helm\n---\n\nIt might help to add --debug to helm upgrade output during failures.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline positive feedback rule"],
                             negativeSignals: [],
@@ -1097,7 +1103,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 3,
                             threshold: 2,
                             knowledgeRef: "knowledge:terraform-state-location",
-                            content: "---\ndescription: Use remote state locks\ntags:\n  - terraform\nobserved_at: 2026-04-04\nsources:\n  - memory:terraform-state-location\n  - skill:terraform\n---\n\nUse remote state with locking enabled before applying shared Terraform stacks.\n",
+                            content: "---\ndescription: Use remote state locks\ntags:\n  - terraform\nobserved_at: 2026-04-04\nxrefs:\n  - memory:terraform-state-location\n  - skill:terraform\n---\n\nUse remote state with locking enabled before applying shared Terraform stacks.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline positive feedback rule"],
                             negativeSignals: [],
@@ -1114,7 +1120,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 2,
                             threshold: 2,
                             knowledgeRef: "knowledge:mixed-signal-rollback",
-                            content: "---\ndescription: Rollback the cluster immediately\nobserved_at: 2026-04-03\nsources:\n  - memory:mixed-signal-rollback\n  - skill:incident\n---\n\nRollback the cluster immediately after any 5xx spike.\n",
+                            content: "---\ndescription: Rollback the cluster immediately\nobserved_at: 2026-04-03\nxrefs:\n  - memory:mixed-signal-rollback\n  - skill:incident\n---\n\nRollback the cluster immediately after any 5xx spike.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline positive feedback rule"],
                             negativeSignals: [],
@@ -1131,7 +1137,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 2,
                             threshold: 2,
                             knowledgeRef: "knowledge:cache-ttl-fact",
-                            content: "---\ndescription: Cache TTL defaults to five minutes\ntags:\n  - cache\n  - platform\nobserved_at: 2026-04-02\nsources:\n  - memory:cache-ttl-fact\n  - skill:platform\n---\n\nThe shared platform cache TTL defaults to five minutes unless the service opts out.\n",
+                            content: "---\ndescription: Cache TTL defaults to five minutes\ntags:\n  - cache\n  - platform\nobserved_at: 2026-04-02\nxrefs:\n  - memory:cache-ttl-fact\n  - skill:platform\n---\n\nThe shared platform cache TTL defaults to five minutes unless the service opts out.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline positive feedback rule"],
                             negativeSignals: [],
@@ -1187,7 +1193,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 2,
                             threshold: 3,
                             knowledgeRef: "knowledge:kafka-rebalance-note",
-                            content: "---\ndescription: Pause consumers during rebalance\ntags:\n  - kafka\n  - ops\nobserved_at: 2026-04-08\nsources:\n  - memory:kafka-rebalance-note\n  - skill:kafka\n---\n\nPause consumers during partition rebalances to avoid duplicate processing while assignments settle.\n",
+                            content: "---\ndescription: Pause consumers during rebalance\ntags:\n  - kafka\n  - ops\nobserved_at: 2026-04-08\nxrefs:\n  - memory:kafka-rebalance-note\n  - skill:kafka\n---\n\nPause consumers during partition rebalances to avoid duplicate processing while assignments settle.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline metadata rule"],
                             negativeSignals: [],
@@ -1204,7 +1210,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 2,
                             threshold: 3,
                             knowledgeRef: "knowledge:gha-token-scope",
-                            content: "---\ndescription: Minimize GitHub token scopes\ntags:\n  - gha\n  - security\nobserved_at: 2026-04-07\nsources:\n  - memory:gha-token-scope\n  - skill:github-actions\n---\n\nUse the narrowest GitHub token scope that still allows the workflow step to succeed.\n",
+                            content: "---\ndescription: Minimize GitHub token scopes\ntags:\n  - gha\n  - security\nobserved_at: 2026-04-07\nxrefs:\n  - memory:gha-token-scope\n  - skill:github-actions\n---\n\nUse the narrowest GitHub token scope that still allows the workflow step to succeed.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline metadata rule"],
                             negativeSignals: [],
@@ -1221,7 +1227,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 2,
                             threshold: 3,
                             knowledgeRef: "knowledge:helm-debug-guess",
-                            content: "---\ndescription: Helm upgrade might need --debug\nobserved_at: 2026-04-05\nsources:\n  - memory:helm-debug-guess\n  - skill:helm\n---\n\nIt might help to add --debug to helm upgrade output during failures.\n",
+                            content: "---\ndescription: Helm upgrade might need --debug\nobserved_at: 2026-04-05\nxrefs:\n  - memory:helm-debug-guess\n  - skill:helm\n---\n\nIt might help to add --debug to helm upgrade output during failures.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline metadata rule"],
                             negativeSignals: [],
@@ -1238,7 +1244,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 2,
                             threshold: 3,
                             knowledgeRef: "knowledge:terraform-state-location",
-                            content: "---\ndescription: Use remote state locks\ntags:\n  - terraform\nobserved_at: 2026-04-04\nsources:\n  - memory:terraform-state-location\n  - skill:terraform\n---\n\nUse remote state with locking enabled before applying shared Terraform stacks.\n",
+                            content: "---\ndescription: Use remote state locks\ntags:\n  - terraform\nobserved_at: 2026-04-04\nxrefs:\n  - memory:terraform-state-location\n  - skill:terraform\n---\n\nUse remote state with locking enabled before applying shared Terraform stacks.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline metadata rule"],
                             negativeSignals: [],
@@ -1255,7 +1261,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 2,
                             threshold: 3,
                             knowledgeRef: "knowledge:mixed-signal-rollback",
-                            content: "---\ndescription: Rollback the cluster immediately\nobserved_at: 2026-04-03\nsources:\n  - memory:mixed-signal-rollback\n  - skill:incident\n---\n\nRollback the cluster immediately after any 5xx spike.\n",
+                            content: "---\ndescription: Rollback the cluster immediately\nobserved_at: 2026-04-03\nxrefs:\n  - memory:mixed-signal-rollback\n  - skill:incident\n---\n\nRollback the cluster immediately after any 5xx spike.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline metadata rule"],
                             negativeSignals: [],
@@ -1272,7 +1278,7 @@ export const DEFAULT_PROMOTION_POLICY_SELECTION = {
                             score: 2,
                             threshold: 3,
                             knowledgeRef: "knowledge:cache-ttl-fact",
-                            content: "---\ndescription: Cache TTL defaults to five minutes\ntags:\n  - cache\n  - platform\nobserved_at: 2026-04-02\nsources:\n  - memory:cache-ttl-fact\n  - skill:platform\n---\n\nThe shared platform cache TTL defaults to five minutes unless the service opts out.\n",
+                            content: "---\ndescription: Cache TTL defaults to five minutes\ntags:\n  - cache\n  - platform\nobserved_at: 2026-04-02\nxrefs:\n  - memory:cache-ttl-fact\n  - skill:platform\n---\n\nThe shared platform cache TTL defaults to five minutes unless the service opts out.\n",
                             blockedBy: [],
                             positiveSignals: ["baseline metadata rule"],
                             negativeSignals: [],

package/dist/commands/improve/distill.js

@@ -34,14 +34,10 @@
  *
  * # Lesson-name derivation rule
  *
- * The proposed lesson ref is `lesson:<original-ref-slug>-lesson`, where
- * `<original-ref-slug>` is `<type>-<name>` from the parsed input ref (so
- * `skill:deploy` → `lesson:skill-deploy-lesson`, and `team//memory:auth-tips`
- * → `lesson:memory-auth-tips-lesson`). Origin prefixes are dropped from the
- * derived name so two sources with the same asset-type/name collapse onto
- * the same lesson queue entry rather than each generating its own — the
- * proposal queue tolerates duplicate refs (id is a UUID), so the human
- * reviewer can decide which one to accept.
+ * A nested input preserves its first legitimate scope segment
+ * (`memory:project-a/deploy` → `lesson:project-a/memory-deploy-lesson`). An
+ * unscoped input stays flat; asset types are not project scopes. Origin prefixes
+ * remain durable provenance but are not embedded in the output path.
  *
  * # Why we do not call `runAgent`
  *
@@ -54,7 +50,7 @@ import fs from "node:fs";
 import distillKnowledgeSystemPrompt from "../../assets/prompts/distill-knowledge-system.md" with { type: "text" };
 import distillLessonSystemPrompt from "../../assets/prompts/distill-lesson-system.md" with { type: "text" };
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
-import { assembleAssetFromString } from "../../core/asset/asset-serialize.js";
+import { assembleAsset, assembleAssetFromString } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter, writeSalienceToFrontmatter } from "../../core/asset/frontmatter.js";
 import { stripMarkdownFences } from "../../core/asset/markdown.js";
 import { authoringRulesForType } from "../../core/authoring-rules.js";
@@ -64,7 +60,7 @@ import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { lintLessonContent } from "../../core/lesson-lint.js";
 import { getDbPath } from "../../core/paths.js";
-import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
+import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { withStateDb } from "../../core/state-db.js";
 import { warnVerbose } from "../../core/warn.js";
 import { closeDatabase, getAllEntries, openIndexDatabase } from "../../indexer/db/db.js";
@@ -82,6 +78,7 @@ import { deriveKnowledgeRef } from "./distill-promotion-policy.js";
 import { buildRefVocabulary, scoreEncodingSalience } from "./encoding-salience.js";
 import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
 import { computeSalience, upsertAssetSalience } from "./salience.js";
+import { bareImproveRef, durableImproveRef } from "./source-identity.js";
 // Re-exported for `reflect.ts`, which applies the same LLM-as-judge gate to
 // reflect proposals (R-5 / #374).
 export { runLessonQualityJudge };
@@ -125,14 +122,21 @@ export function deriveLessonRef(inputRef) {
     // distils into the same lesson namespace as `skill:deploy`. The proposal
     // id (a UUID) keeps the queue entries distinct, so collisions are not a
     // problem — and reviewers want to see them next to each other anyway.
-    const slug = `${parsed.type}-${parsed.name}`.toLowerCase();
+    const parts = parsed.name.split("/");
+    const scope = parts.length > 1 ? parts.shift() : undefined;
+    const slug = `${parsed.type}-${parts.join("-")}`.toLowerCase();
     // Replace anything outside the canonical asset-name charset with `-`. Keep
     // it deterministic so re-runs produce the same ref.
     const safe = slug
         .replace(/[^a-z0-9-]+/g, "-")
         .replace(/-+/g, "-")
         .replace(/^-|-$/g, "");
-    return `lesson:${safe}-lesson`;
+    const safeScope = scope
+        ?.toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return `lesson:${safeScope ? `${safeScope}/` : ""}${safe}-lesson`;
 }
 // ── Content quality validators ──────────────────────────────────────────────
 //
@@ -254,7 +258,7 @@ export function assembleStructuredDistillMarkdown(payload, kind) {
     if (kind === "knowledge" && Array.isArray(payload.sources)) {
         const sources = payload.sources.filter((s) => typeof s === "string" && s.trim().length > 0);
         if (sources.length > 0)
-            fm.sources = sources;
+            fm.xrefs = sources;
     }
     const fmLines = Object.entries(fm)
         .map(([k, v]) => {
@@ -429,6 +433,7 @@ export async function akmDistill(options) {
     }
     // Validate the ref shape up front so a typo never reaches the LLM.
     const parsedInputRef = parseAssetRef(inputRef);
+    const durableInputRef = durableImproveRef(inputRef, options.sourceName);
     const targetKind = options.proposalKind ?? "lesson";
     // Attribution tagging: spread into every distill_invoked event's metadata so
     // the lane that selected this asset is recorded uniformly across all outcome
@@ -457,7 +462,7 @@ export async function akmDistill(options) {
             : "Distill refuses lesson inputs — lessons are the distilled form, not a source.";
         appendEvent({
             eventType: "distill_invoked",
-            ref: inputRef,
+            ref: durableInputRef,
             metadata: {
                 outcome: "skipped",
                 lessonRef: skippedRef,
@@ -485,7 +490,7 @@ export async function akmDistill(options) {
             const runner = resolveImproveProcessRunner(options.improveProfile, "distill", config);
             return runner ? materializeLlmRunnerConnection(runner) : getDefaultLlmConfig(config);
         })();
-    const lookup = options.lookupFn ?? defaultLookup;
+    const lookup = options.lookupFn ?? ((ref) => defaultLookup(ref, stash));
     const readEventsImpl = options.readEventsFn ?? readEvents;
     // R1 opt-out must flow into every computeSalience call this command makes so
     // distill-written rank_score rows use the same weights as preparation's.
@@ -497,7 +502,7 @@ export async function akmDistill(options) {
     let assetContent = null;
     let assetFilePath = null;
     try {
-        const filePath = await lookup(inputRef);
+        const filePath = await lookup(durableInputRef);
         if (filePath && fs.existsSync(filePath)) {
             assetFilePath = filePath;
             assetContent = fs.readFileSync(filePath, "utf8");
@@ -565,7 +570,7 @@ export async function akmDistill(options) {
                         encodingSalience: salienceResult.score,
                         outcomeWeightEnabled,
                     });
-                    upsertAssetSalience(stateDb, inputRef, vector);
+                    upsertAssetSalience(stateDb, durableInputRef, vector);
                 });
             }
             catch {
@@ -576,12 +581,15 @@ export async function akmDistill(options) {
             // Scoring errors never block distillation.
         }
     }
-    const { events } = readEventsImpl({
-        ref: inputRef,
+    const { events: unfilteredEvents } = readEventsImpl({
+        ...(!options.legacyBareState ? { ref: durableInputRef } : {}),
         type: "feedback",
         excludeTags: options.excludeTags,
         includeTags: options.includeTags,
     });
+    const events = options.legacyBareState
+        ? unfilteredEvents.filter((event) => event.ref === durableInputRef || event.ref === bareImproveRef(inputRef))
+        : unfilteredEvents;
     // #267 — feedback exclusion. Filter events whose `ref` matches the
     // exclusion list BEFORE the prompt is built. The original event stream
     // is never mutated; only the `feedback` slice that reaches the LLM is
@@ -608,6 +616,8 @@ export async function akmDistill(options) {
     const promotionResult = await promoteMemoryToKnowledge({
         targetKind,
         inputRef,
+        durableInputRef,
+        sourceName: options.sourceName,
         assetContent,
         filteredEvents,
         config,
@@ -661,7 +671,7 @@ export async function akmDistill(options) {
     }
     // Distill output is a lesson/knowledge (non-wiki) → stash authoring
     // standards. Resolved once for this single call.
-    const standardsContext = resolveStashStandards(stash);
+    const standardsContext = resolveStandardsContext(effectiveLessonRef, stash);
     const baseUserPrompt = buildDistillPrompt({
         inputRef,
         assetContent,
@@ -743,7 +753,7 @@ export async function akmDistill(options) {
         // is observable.
         appendEvent({
             eventType: "distill_invoked",
-            ref: inputRef,
+            ref: durableInputRef,
             metadata: {
                 outcome: "llm_failed",
                 lessonRef: effectiveLessonRef,
@@ -812,7 +822,7 @@ export async function akmDistill(options) {
     if (findings.length > 0) {
         appendEvent({
             eventType: "distill_invoked",
-            ref: inputRef,
+            ref: durableInputRef,
             metadata: {
                 outcome: "validation_failed",
                 lessonRef: effectiveLessonRef,
@@ -882,22 +892,22 @@ export async function akmDistill(options) {
     // structured payload alongside the raw content (matches the shape used by
     // other proposal sources).
     //
-    // D-7 / #398: Inject `sources: [inputRef]` into the LLM-path proposal
-    // frontmatter when the field is absent, providing reviewers with provenance
-    // without requiring them to open event history. A-MEM arXiv:2502.12110 —
-    // all notes carry explicit provenance links.
+    // Serialize canonical provenance into the content that promotion writes.
     const parsed = parseFrontmatter(content);
-    const frontmatterWithSources = { ...parsed.data };
-    if (!Array.isArray(frontmatterWithSources.sources) || frontmatterWithSources.sources.length === 0) {
-        frontmatterWithSources.sources = [inputRef];
-    }
+    const existingXrefs = Array.isArray(parsed.data.xrefs) ? parsed.data.xrefs.map(String) : [];
+    const frontmatterWithXrefs = {
+        ...parsed.data,
+        xrefs: [...new Set([...existingXrefs, durableInputRef])],
+    };
+    delete frontmatterWithXrefs.sources;
+    content = assembleAsset(frontmatterWithXrefs, parsed.content);
     const proposalResult2 = createProposal(stash, {
         ref: effectiveLessonRef,
         source: "distill",
         ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
         payload: {
             content,
-            frontmatter: frontmatterWithSources,
+            frontmatter: frontmatterWithXrefs,
         },
         ...(lessonJudgeConfidence !== undefined ? { confidence: lessonJudgeConfidence } : {}),
         // Attribution tagging: persist the eligibility lane on the proposal.
@@ -906,7 +916,7 @@ export async function akmDistill(options) {
     if (isProposalSkipped(proposalResult2)) {
         appendEvent({
             eventType: "distill_invoked",
-            ref: inputRef,
+            ref: durableInputRef,
             metadata: {
                 outcome: "skipped",
                 lessonRef: effectiveLessonRef,
@@ -928,10 +938,10 @@ export async function akmDistill(options) {
     // G4: content-score the distilled OUTPUT so it carries a real encoding
     // salience (encoding_source='content') from creation — lessons never get
     // another chance (they are refused as distill inputs).
-    persistOutputEncodingSalience(effectiveLessonRef, content, existingRefVocabulary, outcomeWeightEnabled);
+    persistOutputEncodingSalience(durableImproveRef(effectiveLessonRef, options.sourceName), content, existingRefVocabulary, outcomeWeightEnabled);
     appendEvent({
         eventType: "distill_invoked",
-        ref: inputRef,
+        ref: durableInputRef,
         metadata: {
             outcome: "queued",
             lessonRef: effectiveLessonRef,
@@ -962,6 +972,12 @@ export async function akmDistill(options) {
     };
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
-async function defaultLookup(ref) {
-    return resolveAssetPath(ref, { mode: "index-only" });
+async function defaultLookup(ref, stashDir) {
+    return resolveAssetPath(ref, {
+        stashDir,
+        mode: "disk-only",
+        directoryIndexNames: ["SKILL.md"],
+        preserveDirectNameFallback: true,
+        honorOrigin: false,
+    });
 }

package/dist/commands/improve/eligibility.js

@@ -13,6 +13,7 @@ import { getWritableStashDirs, resolveSourceEntries } from "../../indexer/search
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { isDistillRefusedInputType } from "./distill.js";
 import { isStrategyFilteredForAllPasses } from "./improve-strategies.js";
+import { improveStateReadRefs } from "./source-identity.js";
 // Eligibility / candidate-selection predicates for improve. Free functions
 // (no akmImprove closure state) extracted from improve.ts to shrink the
 // orchestrator and make candidate selection independently testable.
@@ -292,15 +293,15 @@ export function shouldDistillMemoryRef(ref, stashDir) {
  * metadata events are ignored so a stray `akm feedback <ref>` invocation
  * without a flag doesn't trigger downstream re-processing.
  */
-export function buildLatestFeedbackTsMap(refs, sinceIso) {
+export function buildLatestFeedbackTsMap(refs, sinceIso, sourceName, includeLegacyBare = false) {
     const out = new Map();
     if (refs.length === 0)
         return out;
-    const refSet = new Set(refs);
+    const refByDurableKey = new Map(refs.flatMap((ref) => improveStateReadRefs(ref, sourceName, includeLegacyBare).map((key) => [key, ref])));
     const { events } = readEvents({ type: "feedback", since: sinceIso });
     for (const e of events) {
-        const ref = e.ref;
-        if (!ref || !refSet.has(ref))
+        const ref = e.ref ? refByDurableKey.get(e.ref) : undefined;
+        if (!ref)
             continue;
         const meta = e.metadata;
         const hasSignal = meta !== undefined && (typeof meta.signal === "string" || typeof meta.note === "string");
@@ -321,16 +322,16 @@ export function buildLatestFeedbackTsMap(refs, sinceIso) {
  * lesson/knowledge ref, not the source memory — joining back through the
  * payload would be fragile.
  */
-export function buildLatestProposalTsMap(refs, source) {
+export function buildLatestProposalTsMap(refs, source, sourceName, includeLegacyBare = false) {
     const out = new Map();
     if (refs.length === 0)
         return out;
-    const refSet = new Set(refs);
+    const refByDurableKey = new Map(refs.flatMap((ref) => improveStateReadRefs(ref, sourceName, includeLegacyBare).map((key) => [key, ref])));
     const eventType = source === "reflect" ? "reflect_invoked" : "distill_invoked";
     const { events } = readEvents({ type: eventType });
     for (const e of events) {
-        const ref = e.ref;
-        if (!ref || !refSet.has(ref))
+        const ref = e.ref ? refByDurableKey.get(e.ref) : undefined;
+        if (!ref)
             continue;
         // For distill_invoked we only count attempts that produced (or attempted
         // to produce) a real proposal — config_disabled / parse-error outcomes

package/dist/commands/improve/extract-prompt.js

@@ -54,8 +54,8 @@ export const EXTRACT_JSON_SCHEMA = {
                     },
                     name: {
                         type: "string",
-                        description: "Kebab-case slug for the new asset.",
-                        pattern: "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+                        description: "Kebab-case slug, optionally under one stable scope/domain segment.",
+                        pattern: "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)?$",
                     },
                     description: {
                         type: "string",