akm-cli 0.10.261010-beta → 0.10.261012-beta

package/dist/core/adapter/adapters/akm-metadata.js

@@ -4,7 +4,7 @@
 import { scanEnvKeyNames } from "../../../commands/env/env.js";
 import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
 import { compileWorkflowSource, workflowStepInstructions } from "../../../workflows/compile.js";
-import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { parseFrontmatter, readFrontmatterDate } from "../../asset/frontmatter.js";
 import { parseMarkdownToc } from "../../asset/markdown.js";
 import { nonEmptyString } from "./shared.js";
 /**
@@ -125,19 +125,10 @@ export function foldRecognizedMetadata(rendererName, file) {
                 const source = nonEmptyString(fm.source);
                 if (source)
                     hints.add(source);
-                const fmObservedAt = nonEmptyString(fm.observed_at);
-                if (fmObservedAt) {
-                    hints.add(`observed_at:${fmObservedAt}`);
-                }
-                else {
-                    try {
-                        const isoDate = file.stat().mtime.toISOString().slice(0, 10);
-                        hints.add(`observed_at:${isoDate}`);
-                    }
-                    catch {
-                        // Non-fatal: skip mtime fallback on stat error
-                    }
-                }
+                // Only a stated observation date is a hint: a file's write time is not one.
+                const observed = readFrontmatterDate(fm, "observed");
+                if (observed)
+                    hints.add(`observed:${observed}`);
                 const expires = nonEmptyString(fm.expires);
                 if (expires)
                     hints.add(`expires:${expires}`);

package/dist/core/asset/frontmatter.js

@@ -11,7 +11,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
-import { existingFileMode, writeFileAtomic } from "../common.js";
+import { asNonEmptyString, existingFileMode, writeFileAtomic } from "../common.js";
 import { recordWrittenPath } from "../write-provenance.js";
 import { assembleAsset, assembleAssetFromString, serializeFrontmatter } from "./asset-serialize.js";
 /**
@@ -53,6 +53,15 @@ export function parseFrontmatter(raw) {
         bodyStartLine: parsedBlock.bodyStartLine,
     };
 }
+/**
+ * Read a date-valued frontmatter key by its bare name (`observed`), falling
+ * back to the legacy `<name>_at` spelling (`observed_at`) that older stashes
+ * still carry. The new name wins when both are present. Writers write only the
+ * bare name.
+ */
+export function readFrontmatterDate(fm, key) {
+    return asNonEmptyString(fm[key]) ?? asNonEmptyString(fm[`${key}_at`]);
+}
 /**
  * Normalize YAML dates to match expected AKM frontmatter types.
  *

package/dist/core/subprocess.js

@@ -135,9 +135,21 @@ function removeSignalGuard() {
  * else handles the signal. A command that handles it itself (`workflow run`,
  * `improve`, task runs) unwinds through its own cleanup, which already aborts
  * its children, and must not have its handling pre-empted by a re-raise.
+ *
+ * They go in BEFORE the spawn ({@link installSignalGuard}): a signal that lands
+ * between the spawn and the registration would otherwise meet the default
+ * disposition, end akm, and leave the new group running (#1230). The listener
+ * runs on the event loop, so it always sees the child registered here.
  */
 function registerLiveGroupChild(child) {
     liveGroupChildren.add(child);
+    return () => {
+        liveGroupChildren.delete(child);
+        if (liveGroupChildren.size === 0)
+            removeSignalGuard();
+    };
+}
+function installSignalGuard() {
     if (!signalGuardHandlers && process.listenerCount("SIGINT") === 0 && process.listenerCount("SIGTERM") === 0) {
         const handlers = [];
         for (const signal of ["SIGINT", "SIGTERM"]) {
@@ -155,11 +167,6 @@ function registerLiveGroupChild(child) {
         }
         signalGuardHandlers = handlers;
     }
-    return () => {
-        liveGroupChildren.delete(child);
-        if (liveGroupChildren.size === 0)
-            removeSignalGuard();
-    };
 }
 /**
  * The joined, human-readable reason ONE managed run's capture is incomplete, or
@@ -383,11 +390,17 @@ export async function runManagedSubprocess(cmd, opts) {
             stderrRead: EMPTY_READ,
         };
     }
+    // A termination signal to this process takes the own-group child down too.
+    const guardsGroup = capture && spawnsOwnProcessGroup();
+    if (guardsGroup)
+        installSignalGuard();
     let proc;
     try {
         proc = spawnFn(cmd, buildSpawnOptions(opts));
     }
     catch (err) {
+        if (guardsGroup && liveGroupChildren.size === 0)
+            removeSignalGuard();
         return {
             exitCode: null,
             stdout: "",
@@ -446,8 +459,7 @@ export async function runManagedSubprocess(cmd, opts) {
         else
             abortSignal.addEventListener("abort", onAbort, { once: true });
     }
-    // A termination signal to this process takes the own-group child down too.
-    const unregisterLiveChild = capture && spawnsOwnProcessGroup() ? registerLiveGroupChild({ proc, terminate: onAbort }) : () => { };
+    const unregisterLiveChild = guardsGroup ? registerLiveGroupChild({ proc, terminate: onAbort }) : () => { };
     // Stream-drain timeout: a short grace once nothing living owns the pipe any
     // more, or a one-hour safety bound when execution itself is unbounded.
     //

package/dist/indexer/passes/memory-inference.js

@@ -28,6 +28,12 @@
  *   A pass runs iff both layers allow it. Existing inferred children are
  *   NEVER deleted — the user keeps what was already produced.
  *
+ * Scope sync: on every run, an existing derived child (`<name>.derived.md`,
+ * `inferred: true`, `derivedFrom` naming its parent) whose normalized scope
+ * differs from its parent's gets only its scope frontmatter rewritten to the
+ * parent's — deterministic, no model call, body and other metadata untouched.
+ * See {@link syncDerivedChildScopes}.
+ *
  * Locked v1 contract:
  *   - LLM access is exclusively via the frozen runner returned by
  *     `resolveIndexPassExecution("memory", config)`.
@@ -37,12 +43,13 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
-import { assembleAsset } from "../../core/asset/asset-serialize.js";
-import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
+import { assembleAsset, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter, parseFrontmatterBlock, readFrontmatterDate, replaceFrontmatterBlocks, } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { bestEffort } from "../../core/best-effort.js";
-import { todayIso } from "../../core/common.js";
+import { asNonEmptyString, existingFileMode, writeFileAtomic } from "../../core/common.js";
 import { concurrentMap } from "../../core/concurrent.js";
 import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
@@ -54,8 +61,10 @@ import { isProcessEnabled } from "../../llm/feature-gate.js";
 import { resolveIndexPassExecution } from "../../llm/index-passes.js";
 import * as memoryInfer from "../../llm/memory-infer.js";
 import { computeBodyHash, getLlmCacheEntry } from "../../storage/repositories/index-llm-cache-repository.js";
+import { pkgVersion } from "../../version.js";
 import { withLlmCache } from "../db/llm-cache.js";
 import { walkMarkdownFiles } from "../walk/walker.js";
+import { applyProvenanceFrontmatter, SCOPE_KEYS, sameScope, scopeFromFrontmatter, } from "./metadata.js";
 /**
  * Frontmatter keys this pass cares about. Constants so a future rename only
  * needs to touch one site.
@@ -66,10 +75,11 @@ const FM_SOURCE = "source";
 const FM_CAPTURE_MODE = "captureMode";
 /**
  * Cache namespace for this pass. Bump it when the cached response semantics
- * change (v3: a cached row may be an explicit no-change decision); rows under an
+ * change (v4: body plus grounded source context; v5: `observed` in the
+ * source context and prompt); rows under an
  * older namespace are never read again, which is a disposable cache miss.
  */
-const MEMORY_INFERENCE_CACHE_VARIANT = "memory-inference-v3";
+const MEMORY_INFERENCE_CACHE_VARIANT = "memory-inference-v5";
 function validateDerivedMemoryDraft(raw) {
     if (!raw || typeof raw !== "object")
         return undefined;
@@ -89,16 +99,19 @@ function validateDerivedMemoryDraft(raw) {
 function validateMemoryInferDecision(raw) {
     return memoryInfer.isMemoryInferNoChange(raw) ? memoryInfer.MEMORY_INFER_NO_CHANGE : validateDerivedMemoryDraft(raw);
 }
+function readCachedMemoryDecision(db, record) {
+    return bestEffort(() => {
+        const entry = getLlmCacheEntry(db, record.filePath, computeBodyHash(record.effectiveInput), MEMORY_INFERENCE_CACHE_VARIANT);
+        return entry ? validateMemoryInferDecision(JSON.parse(entry.resultJson)) : undefined;
+    }, "memory inference cache read corrupt — fall through to recompute");
+}
 function planPendingMemoryRecord(record, ctx) {
     if (ctx.signal?.aborted)
         return { kind: "aborted", record };
     if (fs.existsSync(derivedChildPath(record)))
         return { kind: "existing-child", record };
     if (ctx.db && !ctx.reEnrich) {
-        const cached = bestEffort(() => {
-            const entry = getLlmCacheEntry(ctx.db, record.filePath, computeBodyHash(record.body), MEMORY_INFERENCE_CACHE_VARIANT);
-            return entry ? validateMemoryInferDecision(JSON.parse(entry.resultJson)) : undefined;
-        }, "memory inference cache read corrupt — fall through to recompute");
+        const cached = readCachedMemoryDecision(ctx.db, record);
         if (cached)
             return { kind: "cache-hit", record, decision: cached };
     }
@@ -141,17 +154,17 @@ async function inferPendingMemoryRecord(plan, ctx) {
     const onRetryAttempt = () => {
         retryAttempts += 1;
     };
-    const infer = () => compressMemoryToDerivedMemory(llmRunner, record.body, signal, featureConfig, (event) => warn(`[akm] LLM fallback for ${event.feature}: ${event.reason}`), inferTelemetry, onRetryAttempt, onNotices);
+    const infer = () => compressMemoryToDerivedMemory(llmRunner, record.effectiveInput, signal, featureConfig, (event) => warn(`[akm] LLM fallback for ${event.feature}: ${event.reason}`), inferTelemetry, onRetryAttempt, onNotices);
     let derived = plan.kind === "cache-hit" ? plan.decision : undefined;
     try {
         if (plan.kind === "model") {
             derived = db
-                ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, infer, validateMemoryInferDecision, undefined, MEMORY_INFERENCE_CACHE_VARIANT, {
+                ? await withLlmCache(db, record.filePath, record.effectiveInput, reEnrich ?? false, infer, validateMemoryInferDecision, undefined, MEMORY_INFERENCE_CACHE_VARIANT, {
                     onCacheHit: () => {
                         fromCache = true;
                     },
                 })
-                : await compressMemoryToDerivedMemory(llmRunner, record.body, signal, config, (event) => warn(`[akm] LLM fallback for ${event.feature}: ${event.reason}`), inferTelemetry, onRetryAttempt, onNotices);
+                : await compressMemoryToDerivedMemory(llmRunner, record.effectiveInput, signal, config, (event) => warn(`[akm] LLM fallback for ${event.feature}: ${event.reason}`), inferTelemetry, onRetryAttempt, onNotices);
         }
     }
     catch (error) {
@@ -231,6 +244,7 @@ async function runMemoryInferencePassBody(ctx, provenance) {
         skippedAborted: 0,
         unaccounted: 0,
         htmlErrorCount: 0,
+        scopeSynced: 0,
         writtenPaths: [],
     };
     // Mutable sink threaded into compressMemoryToDerivedMemory so the per-call
@@ -277,7 +291,14 @@ async function runMemoryInferencePassBody(ctx, provenance) {
         warn(`memory inference: skipped — the default bundle at ${primary.path} is not an akm bundle`);
         return completeResult();
     }
-    const pending = collectPendingMemories(primary.path).filter((record) => !options.candidateRefs || options.candidateRefs.has(record.ref));
+    const inCandidates = (ref) => !options.candidateRefs || options.candidateRefs.has(ref);
+    const scan = scanMemories(primary.path);
+    // A read-only default bundle keeps its children as they are; the
+    // deterministic scope rewrite runs before, and apart from, any model work.
+    if (primary.writable !== false && !signal?.aborted) {
+        result.scopeSynced = syncDerivedChildScopes(scan.scopeDrift.filter((drift) => inCandidates(drift.parentRef)));
+    }
+    const pending = scan.pending.filter((record) => inCandidates(record.ref));
     result.considered = pending.length;
     if (pending.length === 0)
         return completeResult();
@@ -379,16 +400,37 @@ async function runMemoryInferencePassBody(ctx, provenance) {
     return completeResult();
 }
 // ── Pending detection ───────────────────────────────────────────────────────
+/**
+ * Pending parents the `minPendingCount` gate should count: those with no cached
+ * no-change decision for their current effective input. A decided parent stays unstamped
+ * by design (so an edit re-opens it), but a pass made only of cached decisions
+ * makes no model call. Read-only; `db` absent counts every pending parent.
+ */
+export function countPendingMemoriesNeedingDecision(stashRoot, db) {
+    const pending = collectPendingMemories(stashRoot);
+    if (!db)
+        return pending.length;
+    return pending.filter((record) => readCachedMemoryDecision(db, record) !== memoryInfer.MEMORY_INFER_NO_CHANGE).length;
+}
 /**
  * Walk `<stashRoot>/memories/` (recursively) and return every memory that
  * still needs inference. The directory may not exist on a fresh stash; that
  * is treated as "no pending memories" rather than an error.
  */
 export function collectPendingMemories(stashRoot) {
+    return scanMemories(stashRoot).pending;
+}
+/**
+ * One walk of `<stashRoot>/memories/`: the pending parents, and the existing
+ * derived children whose scope has drifted from their parent's.
+ */
+function scanMemories(stashRoot) {
     const memoriesDir = path.join(stashRoot, "memories");
     if (!fs.existsSync(memoriesDir))
-        return [];
+        return { pending: [], scopeDrift: [] };
     const out = [];
+    const parentScopes = new Map();
+    const children = [];
     const walked = walkMarkdownFiles(memoriesDir);
     if (!walked.complete) {
         warn(`memory inference: directory scan under ${memoriesDir} is incomplete — some memories may be missing`);
@@ -403,21 +445,86 @@ export function collectPendingMemories(stashRoot) {
             continue;
         }
         const parsed = parseFrontmatter(raw);
-        if (!isPendingMemory(parsed.data, filePath))
-            continue;
         const relName = toMemoryName(memoriesDir, filePath);
         if (!relName)
             continue;
+        if (relName.endsWith(".derived")) {
+            children.push({ filePath, name: relName, data: parsed.data });
+            continue;
+        }
+        parentScopes.set(relName, scopeFromFrontmatter(parsed.data));
+        if (!isPendingMemory(parsed.data, filePath))
+            continue;
         out.push({
             filePath,
             stashRoot,
             ref: conceptIdFromTypeName("memory", relName),
             data: parsed.data,
-            body: parsed.content,
+            effectiveInput: memoryInferenceInput(parsed.content, parsed.data),
             name: relName,
         });
     }
-    return out;
+    const scopeDrift = [];
+    for (const child of children) {
+        const parentName = child.name.slice(0, -".derived".length);
+        const scope = parentScopes.get(parentName);
+        if (!scope || !isDerivedChildOf(child.data, parentName))
+            continue;
+        if (sameScope(scopeFromFrontmatter(child.data), scope))
+            continue;
+        scopeDrift.push({
+            childPath: child.filePath,
+            parentRef: conceptIdFromTypeName("memory", parentName),
+            parentName,
+            scope,
+        });
+    }
+    return { pending: out, scopeDrift };
+}
+/** True only for a file this pass derived from `parentName`: `inferred: true` and a matching `derivedFrom`. */
+function isDerivedChildOf(fm, parentName) {
+    if (fm[FM_INFERRED] !== true)
+        return false;
+    const derivedFrom = asNonEmptyString(fm.derivedFrom);
+    return derivedFrom === parentName || derivedFrom === conceptIdFromTypeName("memory", parentName);
+}
+/**
+ * Section markers of the effective input; `memory-infer-user.md` names them.
+ * The context comes first and is pretty-printed JSON, whose lines are never
+ * exactly `Body:`, so the first such line always starts the raw body.
+ */
+const SOURCE_CONTEXT_MARKER = "Source context:";
+const BODY_MARKER = "Body:";
+/** The non-empty strings of a frontmatter list; anything else is no list. */
+function stringList(raw) {
+    return Array.isArray(raw) ? raw.map(asNonEmptyString).filter((value) => value !== undefined) : [];
+}
+/**
+ * The effective input: a fixed selection of existing source fields (never
+ * arbitrary frontmatter or model-authored authority) as JSON, then the raw
+ * trimmed body. One string drives the request and every cache lookup.
+ */
+function memoryInferenceInput(body, fm) {
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return "";
+    const sourceContext = {};
+    for (const key of ["title", "description", "evidence", "source", "observed", "created", "updated"]) {
+        const value = key === "observed" ? readFrontmatterDate(fm, key) : asNonEmptyString(fm[key]);
+        if (value)
+            sourceContext[key] = value;
+    }
+    for (const key of ["evidenceSources", "xrefs", "sources"]) {
+        const values = stringList(fm[key]);
+        if (values.length)
+            sourceContext[key] = values;
+    }
+    const entry = { type: "memory", name: "source" };
+    applyProvenanceFrontmatter(entry, fm);
+    if (entry.provenance?.sources)
+        sourceContext.provenance = { sources: entry.provenance.sources };
+    sourceContext.scope = scopeFromFrontmatter(fm);
+    return `${SOURCE_CONTEXT_MARKER}\n${JSON.stringify(sourceContext, null, 2)}\n\n${BODY_MARKER}\n${trimmedBody}`;
 }
 /**
  * Predicate: true when the parsed frontmatter indicates the memory has not
@@ -502,6 +609,11 @@ async function writeDerivedMemory(parent, derived) {
     }
 }
 function renderDerivedMemory(parent, derived) {
+    // Generation is when and by what this file was written: deterministic, never
+    // model-authored and never sent to the model. `updated` is that same instant
+    // as the child's own modification date. Neither says when the facts were
+    // observed or that they were verified, so no `verified` is stamped.
+    const generatedAt = new Date().toISOString();
     const fm = {
         [FM_INFERRED]: true,
         [FM_CAPTURE_MODE]: "background",
@@ -513,8 +625,27 @@ function renderDerivedMemory(parent, derived) {
         searchHints: derived.searchHints,
         title: derived.title,
         derivedFrom: parent.name,
-        updated: todayIso(),
+        generated: { by: `akm/${pkgVersion}`, at: generatedAt },
+        updated: generatedAt.slice(0, 10),
     };
+    // The source's own explicit observation date and evidence are carried as
+    // written. A missing one stays missing: `updated` and mtime are not dates of
+    // the facts.
+    const observed = readFrontmatterDate(parent.data, "observed");
+    if (observed)
+        fm.observed = observed;
+    const evidence = asNonEmptyString(parent.data.evidence);
+    if (evidence)
+        fm.evidence = evidence;
+    const evidenceSources = stringList(parent.data.evidenceSources);
+    if (evidenceSources.length)
+        fm.evidenceSources = evidenceSources;
+    const sources = { type: "memory", name: parent.name };
+    applyProvenanceFrontmatter(sources, parent.data);
+    if (sources.provenance?.sources)
+        fm.provenance = { sources: sources.provenance.sources };
+    for (const [key, value] of Object.entries(scopeFromFrontmatter(parent.data)))
+        fm[`scope_${key}`] = value;
     return assembleAsset(fm, `# ${derived.title.trim()}\n\n${derived.content.trim()}\n`);
 }
 function markParentProcessed(parent) {
@@ -554,3 +685,47 @@ function markParentProcessed(parent) {
         warn(`memory inference: failed to mark parent processed ${parent.filePath}: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/**
+ * Rewrite only the scope frontmatter of each drifted child to its parent's
+ * normalized scope: the flat `scope_*` keys are set, stale ones and a legacy
+ * nested `scope:` removed, and every other byte — body included — kept. No
+ * model call. Each file is re-read and re-checked first, so a child edited
+ * since the walk is judged as it is now; one that no longer drifts, is no
+ * longer a derived child of that parent, or whose frontmatter cannot be edited
+ * in place is left untouched. Like {@link markParentProcessed}, this is a
+ * frontmatter-only exception to `writeAssetToSource`, written atomically and
+ * journaled so the caller indexes and commits it. Returns the rewrite count.
+ */
+function syncDerivedChildScopes(drifts) {
+    let synced = 0;
+    const scopeKeys = ["scope", ...SCOPE_KEYS.map((key) => `scope_${key}`)];
+    for (const drift of drifts) {
+        try {
+            const raw = fs.readFileSync(drift.childPath, "utf8");
+            const data = parseFrontmatter(raw).data;
+            if (!isDerivedChildOf(data, drift.parentName) || sameScope(scopeFromFrontmatter(data), drift.scope))
+                continue;
+            const flat = {};
+            for (const key of SCOPE_KEYS)
+                if (drift.scope[key] !== undefined)
+                    flat[`scope_${key}`] = drift.scope[key];
+            const lines = Object.keys(flat).length > 0 ? serializeFrontmatter(flat).split("\n") : [];
+            const next = replaceFrontmatterBlocks(raw, scopeKeys, lines);
+            const expected = { ...data };
+            for (const key of scopeKeys)
+                delete expected[key];
+            Object.assign(expected, flat);
+            if (next === null || !isDeepStrictEqual(parseFrontmatter(next).data, expected)) {
+                warn(`memory inference: scope of ${drift.childPath} differs from its parent but cannot be rewritten in place`);
+                continue;
+            }
+            writeFileAtomic(drift.childPath, next, existingFileMode(drift.childPath));
+            recordWrittenPath(drift.childPath);
+            synced += 1;
+        }
+        catch (err) {
+            warn(`memory inference: failed to sync scope of ${drift.childPath}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return synced;
+}

package/dist/indexer/search/db-search.js

@@ -581,6 +581,8 @@ export async function buildDbHit(input) {
         type: input.entry.type,
         stashDir: entryStashDir,
         bundleId: input.bundleId,
+        defaultBundleId,
+        descriptionSource: input.entry.source,
         db: input.db,
         eligible: input.eligible,
     });

package/dist/indexer/search/search-attribution.js

@@ -13,10 +13,15 @@ export function copySearchHitAttribution(from, to, outputDescription) {
     const memoryInference = from[ATTRIBUTION]?.memoryInference;
     if (!memoryInference)
         return;
-    const memorySurvives = memoryInference.exposure !== "surface" ||
-        (memoryInference.surfaceDescription !== undefined && memoryInference.surfaceDescription === outputDescription);
-    if (memorySurvives)
+    if (memoryInference.exposure !== "surface") {
         attachSearchHitAttribution(to, { memoryInference });
+    }
+    else if (memoryInference.surfaceFields?.includes("description") &&
+        memoryInference.surfaceDescription !== undefined &&
+        memoryInference.surfaceDescription === outputDescription) {
+        // Curate emits descriptions, not tags. Carry only the field it retained.
+        attachSearchHitAttribution(to, { memoryInference: { ...memoryInference, surfaceFields: ["description"] } });
+    }
 }
 export function getSearchHitAttribution(target) {
     return target[ATTRIBUTION];

package/dist/indexer/search/search-hit-enrichers.js

@@ -4,6 +4,7 @@
 import { displayRef } from "../../core/asset/resolve-ref.js";
 import { presentationFor } from "../../core/type-presentation.js";
 import { getDerivedForParent, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
+import { extractDirTagsFromName, extractTagsFromPath } from "../passes/metadata.js";
 import { getRenderer } from "../walk/file-context.js";
 import { attachSearchHitAttribution } from "./search-attribution.js";
 /**
@@ -17,18 +18,18 @@ export async function enrichSearchHit(hit, ctx) {
         renderer?.enrichSearchHit?.(hit, ctx.stashDir);
     }
     if (ctx.type === "memory" && ctx.db)
-        surfaceDerivedMemory(hit, ctx.db, ctx.bundleId, ctx.eligible);
+        surfaceDerivedMemory(hit, ctx.db, ctx);
 }
 /**
  * Phase 5A / Advantage D5 — when a parent memory has a `.derived` child
- * indexed (the LLM-distilled lesson surface), rewrite the parent hit to
- * surface the derived child's description / tags AND set `expandTo` to the
+ * indexed (the LLM-distilled lesson surface), fill missing parent metadata
+ * from the derived child's description / tags AND set `expandTo` to the
  * derived child's ref so callers can fetch it via `akm show <ref>`.
  *
  * The parent ref is preserved on the hit — only the surface text is
- * swapped, so links and provenance still point at the canonical parent.
+ * filled, so links and provenance still point at the canonical parent.
  */
-function surfaceDerivedMemory(hit, db, bundleId, eligible) {
+function surfaceDerivedMemory(hit, db, ctx) {
     // Never recurse: a `.derived` hit is itself the child surface; leaving
     // it untouched also avoids `<parent>.derived.derived` chains.
     if (hit.name.toLowerCase().endsWith(".derived"))
@@ -37,25 +38,26 @@ function surfaceDerivedMemory(hit, db, bundleId, eligible) {
     // entry's name so we don't depend on whatever wiki/registry prefix `hit.ref`
     // carries. INTERNAL lookup key into `getDerivedForParent`: the `derived_from`
     // column stores this same conceptId grammar.
-    const derived = getDerivedForParent(db, `memories/${hit.name}`, bundleId);
-    if (!derived || (eligible && !eligible(derived)))
+    const derived = getDerivedForParent(db, `memories/${hit.name}`, ctx.bundleId);
+    if (!derived || (ctx.eligible && !ctx.eligible(derived)))
         return;
-    // Swap description / tags from the derived child (SourceSearchHit carries no
-    // `searchHints`).
+    // Fields fall back independently. Preserve authored qualifications and tags
+    // that add information beyond the generated filename/directory tokens.
     const surfaceFields = [];
     let surfaceDescription;
-    if (typeof derived.entry.description === "string" && derived.entry.description.length > 0) {
+    if ((!hit.description?.trim() || ctx.descriptionSource === "filename") && derived.entry.description?.trim()) {
         hit.description = derived.entry.description;
         surfaceDescription = derived.entry.description;
         surfaceFields.push("description");
     }
-    if (Array.isArray(derived.entry.tags) && derived.entry.tags.length > 0) {
+    const generatedTags = new Set([...extractTagsFromPath(`${hit.name}.md`, "."), ...extractDirTagsFromName(hit.name)]);
+    if (!hit.tags?.some((tag) => tag.trim() && !generatedTags.has(tag.trim().toLowerCase())) &&
+        derived.entry.tags?.some((tag) => tag.trim())) {
         hit.tags = derived.entry.tags;
         surfaceFields.push("tags");
     }
-    // `expandTo` is a user-facing `akm show <ref>` target, so emit the 0.9.0
-    // short conceptId grammar (`memories/<name>`).
-    hit.expandTo = displayRef({ type: "memory", name: derived.entry.name });
+    // Retain the parent's bundle qualification so expansion resolves the same child.
+    hit.expandTo = displayRef({ type: "memory", name: derived.entry.name, bundleId: ctx.bundleId }, ctx.defaultBundleId);
     const childRef = getItemRefById(db, derived.id);
     if (childRef && surfaceFields.length > 0) {
         attachSearchHitAttribution(hit, {

package/dist/llm/memory-infer.js

@@ -62,7 +62,9 @@ export const DERIVED_MEMORY_JSON_SCHEMA = {
     additionalProperties: false,
 };
 /**
- * Compress a single memory body into one derived memory via the configured LLM.
+ * Compress a single memory into one derived memory via the configured LLM.
+ * `body` is the pass's effective input (a `Source context:` section, then the
+ * raw body after `Body:`), appended verbatim to the user prompt.
  *
  * Returns the draft, or {@link MEMORY_INFER_NO_CHANGE} when the model explicitly
  * decides the memory needs no derived memory. Returns `undefined` on any failure

package/dist/output/renderers.js

@@ -12,7 +12,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { listKeys as listVaultKeys } from "../commands/env/env.js";
-import { parseFrontmatter } from "../core/asset/frontmatter.js";
+import { parseFrontmatter, readFrontmatterDate } from "../core/asset/frontmatter.js";
 import { asNonEmptyString, hasErrnoCode } from "../core/common.js";
 import { extractCommentMetadata } from "../indexer/passes/metadata.js";
 import { registerRenderer } from "../indexer/walk/file-context.js";
@@ -390,7 +390,7 @@ const taskMdRenderer = {
 // ── 8. session-md (#561) ─────────────────────────────────────────────────────
 /**
  * Renderer for the `session` asset type (#561). A session asset is generated by
- * the `extract` pass and carries `harness`, `started_at`/`ended_at`, `project`,
+ * the `extract` pass and carries `harness`, `started`/`ended`, `project`,
  * `log_path`, and `access` frontmatter plus an LLM `## Summary` / `## Key topics`
  * body. The renderer surfaces a human-readable one-liner (harness + date +
  * project) and concrete `access` instructions rather than dumping raw
@@ -404,8 +404,8 @@ const sessionMdRenderer = {
         const fm = parsed.data;
         const harness = asNonEmptyString(fm.harness);
         const project = asNonEmptyString(fm.project);
-        const startedAt = asNonEmptyString(fm.started_at);
-        const endedAt = asNonEmptyString(fm.ended_at);
+        const startedAt = readFrontmatterDate(fm, "started");
+        const endedAt = readFrontmatterDate(fm, "ended");
         const logPath = asNonEmptyString(fm.log_path);
         const access = asNonEmptyString(fm.access);
         const description = asNonEmptyString(fm.description);

package/dist/output/text/show-format.js

@@ -25,7 +25,7 @@ export function formatShowPlain(r, detail) {
         lines.push(`evidence: ${String(r.evidence).replace(/\s+/g, " ")}`);
     if (Array.isArray(r.evidenceSources))
         lines.push(`evidenceSources: ${r.evidenceSources.join(", ")}`);
-    if (r.evidence && r.provenance)
+    if (r.provenance)
         lines.push(`provenance: ${JSON.stringify(r.provenance)}`);
     if (r.workflowTitle)
         lines.push(`workflowTitle: ${String(r.workflowTitle)}`);

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

@@ -31086,7 +31086,7 @@ function formatShowPlain(r, detail) {
     lines.push(`evidence: ${String(r.evidence).replace(/\s+/g, " ")}`);
   if (Array.isArray(r.evidenceSources))
     lines.push(`evidenceSources: ${r.evidenceSources.join(", ")}`);
-  if (r.evidence && r.provenance)
+  if (r.provenance)
     lines.push(`provenance: ${JSON.stringify(r.provenance)}`);
   if (r.workflowTitle)
     lines.push(`workflowTitle: ${String(r.workflowTitle)}`);
@@ -40808,6 +40808,9 @@ function parseFrontmatter(raw) {
     bodyStartLine: parsedBlock.bodyStartLine
   };
 }
+function readFrontmatterDate(fm, key) {
+  return asNonEmptyString(fm[key]) ?? asNonEmptyString(fm[`${key}_at`]);
+}
 function normalizeYamlValues(value) {
   if (value instanceof Date) {
     const y = value.getUTCFullYear();
@@ -46030,15 +46033,9 @@ function foldRecognizedMetadata(rendererName, file) {
         const source = nonEmptyString2(fm.source);
         if (source)
           hints.add(source);
-        const fmObservedAt = nonEmptyString2(fm.observed_at);
-        if (fmObservedAt) {
-          hints.add(`observed_at:${fmObservedAt}`);
-        } else {
-          try {
-            const isoDate = file.stat().mtime.toISOString().slice(0, 10);
-            hints.add(`observed_at:${isoDate}`);
-          } catch {}
-        }
+        const observed = readFrontmatterDate(fm, "observed");
+        if (observed)
+          hints.add(`observed:${observed}`);
         const expires = nonEmptyString2(fm.expires);
         if (expires)
           hints.add(`expires:${expires}`);