akm-cli 0.9.17-alpha.7 → 0.9.17-alpha.9

package/dist/commands/proposal/validators/proposals.js

@@ -4,12 +4,21 @@
 /** Proposal validation and the one content repair applied before promotion. */
 import { repairTruncatedDescription } from "../../../core/text-truncation.js";
 import { splitFrontmatter } from "../../improve/reflect-noise.js";
+import { isRetireProposal } from "../proposal-types.js";
 import { runProposalValidators } from "./proposal-validators.js";
 /**
  * Validate a proposal before promotion: it must parse and carry a body, and a
  * type with a canonical validator runs it.
+ *
+ * A retire proposal (alpha.9 consolidate pair pass) writes no new content —
+ * it deletes an asset that already passed validation when IT was created —
+ * so the content-quality validators (built for new/updated bodies: a
+ * description, lesson shape, reflect size ratio, …) do not apply and are
+ * skipped entirely rather than misreading the empty body as a defect.
  */
 export function validateProposal(proposal) {
+    if (isRetireProposal(proposal))
+        return { ok: true, findings: [] };
     return runProposalValidators(proposal);
 }
 /**

package/dist/commands/read/curate.js

@@ -9,12 +9,15 @@
  * needed to act (ref, run, parameters, follow-up command).
  *
  * Curation is one search with the fused ranking, the top `limit` hits, and
- * per-hit enrichment (preview, run and parameters, graph support refs). An
- * optional reranker reorders the top fused candidates first.
+ * per-hit enrichment (preview, run and parameters, support refs from the
+ * hit's declared links). An optional reranker reorders the top fused
+ * candidates first.
  *
  * The exported `akmCurate()` API is the single entry point; tests can also
  * drive `curateSearchResults` with a fixture search response.
  */
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
@@ -212,7 +215,7 @@ async function enrichCuratedStashHit(query, hit, selectedRefs, eventSource) {
     }
     const description = shown?.description ?? hit.description;
     const preview = buildCuratedPreview(shown, hit);
-    const supportRefs = buildCurateSupportRefs(shown?.related?.hits, selectedRefs, hit.ref);
+    const supportRefs = buildCurateSupportRefs(shown?.links, selectedRefs, hit.ref);
     const item = {
         source: "local",
         type: shown?.type ?? hit.type,
@@ -324,17 +327,41 @@ async function maybeRerankCuratedStashHits(query, hits) {
 function rerankDocumentTexts(hits) {
     return hits.map((hit) => [hit.name, hit.description, searchHitContent(hit)].filter(Boolean).join("\n").slice(0, RERANK_DOCUMENT_CHARS));
 }
-/** Up to {@link MAX_CURATE_SUPPORT_REFS} graph-related assets not already selected. */
-function buildCurateSupportRefs(relatedHits, selectedRefs, ownerRef) {
+/**
+ * Up to {@link MAX_CURATE_SUPPORT_REFS} assets the hit's declared links (#935)
+ * name, not already selected: what the hit links to first, then what links to
+ * it, in the order `akm show` lists them. The LLM entity graph's `related`
+ * list no longer feeds them.
+ */
+function buildCurateSupportRefs(links, selectedRefs, ownerRef) {
     const supportRefs = [];
-    for (const hit of relatedHits ?? []) {
-        if (!hit.ref || hit.ref === ownerRef || selectedRefs.has(hit.ref))
-            continue;
-        if (supportRefs.some((existing) => existing.ref === hit.ref))
-            continue;
-        supportRefs.push({ ref: hit.ref, type: hit.type, reason: "Related asset via shared entities." });
-        if (supportRefs.length >= MAX_CURATE_SUPPORT_REFS)
-            break;
+    for (const [part, direction] of [
+        ["outgoing", "from"],
+        ["incoming", "to"],
+    ]) {
+        for (const [kind, group] of Object.entries(links?.[part] ?? {})) {
+            for (const ref of group.refs) {
+                if (ref === ownerRef || selectedRefs.has(ref) || supportRefs.some((existing) => existing.ref === ref))
+                    continue;
+                const type = supportRefType(ref);
+                supportRefs.push({
+                    ref,
+                    ...(type ? { type } : {}),
+                    reason: `Declared link (${kind}) ${direction} this asset.`,
+                });
+                if (supportRefs.length >= MAX_CURATE_SUPPORT_REFS)
+                    return supportRefs;
+            }
+        }
     }
     return supportRefs;
 }
+/** The asset type a ref's conceptId names (`memories/x` → `memory`), when it names one. */
+function supportRefType(ref) {
+    try {
+        return typeNameFromConceptId(parseBundleRef(ref).conceptId)?.type;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/commands/read/knowledge.js

@@ -612,8 +612,9 @@ export async function writeMarkdownAsset(options) {
     // no longer trigger reindexes, so keeping the index current is the writer's
     // job. Demoted files reindex under their own containing root (usually the
     // write target itself; the working stash when writing to a --target) so
-    // `--belief current` filtering and the beliefState ranking demotion take
-    // effect without waiting for the next full index.
+    // `--belief current` filtering takes effect without waiting for the next
+    // full index. (alpha.4 removed belief weights from ranking; `--belief` is
+    // the only reader of `beliefState` today.)
     const demotedInTargetRoot = demotedByRoot.get(source.path) ?? [];
     demotedByRoot.delete(source.path);
     await indexWrittenAssets(source.path, [result.path, ...demotedInTargetRoot], { bundleId: resolved.ref.origin });

package/dist/commands/read/show.js

@@ -24,7 +24,7 @@ import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { extractSection, markdownFragmentSlugs } from "../../core/asset/markdown.js";
 import { buildMarkdownLeadContext, fragmentForSelector, MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS, } from "../../core/asset/markdown-fragments.js";
-import { displayRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
+import { displayRef, displayRefForConceptId, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { META_DIR, parseMetaRef, readMetaFile } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString, isWithin } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
@@ -33,7 +33,6 @@ import { appendEvent } from "../../core/events.js";
 import { SCRIPT_EXTENSIONS } from "../../core/recognition-util.js";
 import { presentationFor } from "../../core/type-presentation.js";
 import { warn, warnOnce } from "../../core/warn.js";
-import { listRelatedPathsForFile } from "../../indexer/graph/graph-related.js";
 import { lookupBundleRef, lookupBundleRefWithResolution } from "../../indexer/indexer.js";
 import { projectMarkdownFragmentContent } from "../../indexer/passes/metadata.js";
 import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.js";
@@ -43,6 +42,7 @@ import { buildFileContext, buildRenderContext, getRenderer, } from "../../indexe
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { withIndexDb } from "../../storage/repositories/index-db.js";
 import { getIndexedMarkdownFragment } from "../../storage/repositories/index-fts-repository.js";
+import { readEntryLinks } from "../../storage/repositories/index-links-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 import { buildWorkflowAction } from "../../workflows/renderer.js";
 import { getActiveWorkflowRun } from "../../workflows/runtime/runs.js";
@@ -318,12 +318,13 @@ export async function showLocal(input) {
     response.type = indexedEntry.type;
     response.name = indexedEntry.name;
     const isPrimaryStash = source?.isDefault === true;
+    const displayDefaultBundle = config.defaultBundle ?? (isPrimaryStash ? indexedEntry.bundleId : undefined);
     const canonicalRef = displayRef({
         type: indexedEntry.type,
         name: presentedName,
         conceptId: indexedEntry.conceptId,
         bundleId: indexedEntry.bundleId,
-    }, config.defaultBundle ?? (isPrimaryStash ? indexedEntry.bundleId : undefined));
+    }, displayDefaultBundle);
     if (parsed.fragment && indexedFragment) {
         const selectedFragmentId = indexedFragment.fragments[indexedFragment.ordinal].fragmentId;
         const selectedRef = `${canonicalRef}#${selectedFragmentId}`;
@@ -382,19 +383,7 @@ export async function showLocal(input) {
         origin: source?.registryId ?? null,
         editable,
         ...(!editable ? { editHint: buildEditHint(canonicalRef) } : {}),
-        related: (() => {
-            try {
-                return withIndexDb((db) => {
-                    const related = listRelatedPathsForFile(sourceStashDir, assetPath, 5, db);
-                    return { total: related.length, hits: related };
-                });
-            }
-            catch (err) {
-                rethrowIfTestIsolationError(err);
-                rethrowIfDataDirUnreadable(err);
-                return { total: 0, hits: [] };
-            }
-        })(),
+        ...showLinks(indexedEntry.itemRef, displayDefaultBundle),
     };
     const activeRun = await getActiveWorkflowRun(getCurrentWorkflowScopeKey());
     if (activeRun) {
@@ -408,6 +397,56 @@ export async function showLocal(input) {
     }
     return fullResponse;
 }
+/** Refs listed per kind of declared link; `total` still counts them all (one memory is named by 1,437 others). */
+const LINKS_PER_KIND = 10;
+/**
+ * The declared links (#935) of an indexed asset, grouped by kind: outgoing in
+ * authored order, incoming by ref, and unresolved tokens as authored. Empty
+ * parts are omitted, and the field when nothing links either way.
+ */
+function showLinks(itemRef, defaultBundle) {
+    let rows;
+    try {
+        rows = withIndexDb((db) => readEntryLinks(db, itemRef));
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        rethrowIfDataDirUnreadable(err);
+        return {};
+    }
+    const outgoing = [];
+    const unresolved = [];
+    for (const row of rows.outgoing) {
+        if (row.conceptId === undefined)
+            unresolved.push({ kind: row.kind, ref: row.raw ?? "" });
+        else
+            outgoing.push({ kind: row.kind, ref: displayRefForConceptId(row.conceptId, row.bundleId, defaultBundle) });
+    }
+    const incoming = rows.incoming.map((row) => ({
+        kind: row.kind,
+        ref: displayRefForConceptId(row.conceptId ?? "", row.bundleId, defaultBundle),
+    }));
+    const links = {
+        ...groupLinks("outgoing", outgoing),
+        ...groupLinks("incoming", incoming),
+        ...groupLinks("unresolved", unresolved),
+    };
+    return Object.keys(links).length > 0 ? { links } : {};
+}
+function groupLinks(part, rows) {
+    if (rows.length === 0)
+        return {};
+    const groups = {};
+    for (const kind of [...new Set(rows.map((row) => row.kind))].sort())
+        groups[kind] = { total: 0, refs: [] };
+    for (const { kind, ref } of rows) {
+        const group = groups[kind];
+        group.total++;
+        if (group.refs.length < LINKS_PER_KIND)
+            group.refs.push(ref);
+    }
+    return { [part]: groups };
+}
 /**
  * Warn and ignore body fragments for namespaces whose authored bytes are
  * sensitive. `warnOnce`-keyed on the exact ref: `akmShowUnified` calls this

package/dist/commands/sources/info.js

@@ -10,6 +10,7 @@ import { formatRegistryUrl } from "../../core/registry-url.js";
 import { error } from "../../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { getEntryCount, getEntryCountByType } from "../../storage/repositories/index-entries-repository.js";
+import { countLinksByKind } from "../../storage/repositories/index-links-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
 import { pkgVersion } from "../../version.js";
 /**
@@ -99,9 +100,11 @@ function readIndexStats(resolvedPath) {
     let db;
     try {
         db = openExistingDatabase(resolvedPath);
+        const links = countLinksByKind(db);
         return {
             entryCount: getEntryCount(db),
             byType: getEntryCountByType(db),
+            ...(Object.keys(links).length > 0 ? { links } : {}),
             lastBuiltAt: getMeta(db, "builtAt") ?? null,
             hasEmbeddings: getMeta(db, "hasEmbeddings") === "1",
         };

package/dist/commands/sources/stash-cli.js

@@ -83,10 +83,10 @@ export const indexCommand = defineCommand({
     async run({ args }) {
         await runWithJsonErrors(async () => {
             if (getHyphenatedBoolean(args, "enrich") || getParsedInvocation().getFlagValue("--enrich") !== undefined) {
-                throw new UsageError("`akm index --enrich` has been removed. Plain `akm index` now performs metadata enrichment by default.");
+                throw new UsageError("`akm index --enrich` has been removed. Metadata enrichment during indexing is retired; it never runs.");
             }
             if (getHyphenatedBoolean(args, "re-enrich") || getParsedInvocation().getFlagValue("--re-enrich") !== undefined) {
-                throw new UsageError("`akm index --re-enrich` has been removed. Re-enrichment of index-time LLM passes is not exposed in this slice.");
+                throw new UsageError("`akm index --re-enrich` has been removed. Metadata enrichment during indexing is retired; there is nothing to re-enrich.");
             }
             // #956: opt-in, non-blocking rebuild lock — never gates a human-typed
             // `akm index` (it only warns and contends), but a scheduled/opportunistic

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

@@ -193,6 +193,8 @@ const DOCUMENT_JSON_CARRIED_FIELDS = [
     "wikiRole",
     "sources",
     "evidenceSources",
+    // #935: a workflow's step targets and a task's target, read as declared links.
+    "uses",
     // D2 (#730): the OKF v0.2 provenance `promoteProposal` stamps onto AKM-native
     // writes (generated/verified/sources, namespaced — see `types.ts`'s
     // `OkfProvenance` doc). Carried so the akm adapter rereads what it wrote and

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

@@ -54,6 +54,7 @@
  * concern (Chunk 4/5), not recognition's. On the valid Chunk-0b fixture this
  * distinction never triggers.
  */
+import { parseBuiltinCommandAction } from "../../../commands/command/builtin-action.js";
 import { scanEnvKeyNames } from "../../../commands/env/env.js";
 import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
 import { compileWorkflowSource, workflowStepInstructions } from "../../../workflows/compile.js";
@@ -125,6 +126,25 @@ function applyFrontmatterDescriptionAndTags(fm, out) {
         }
     }
 }
+/** The command a stored `akm/command` action runs; inline content names no asset. */
+function storedCommandRef(action) {
+    return action?.kind === "stored" ? action.ref : undefined;
+}
+/** The asset a workflow step targets: its `uses:` ref, or the ref of a stored `akm/command`. Prose and `run:` steps target none. */
+function workflowStepTarget(spec) {
+    if (!spec?.uses)
+        return undefined;
+    if (spec.uses !== "akm/command")
+        return spec.uses;
+    if (spec.commandMode !== "stored-ref")
+        return undefined;
+    try {
+        return storedCommandRef(parseBuiltinCommandAction(spec.with));
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Collect + finalize a searchHints set the way every contributor does (`Array.from(hints).filter(Boolean)`, assigned only when non-empty). */
 function finalizeHints(out, hints) {
     if (hints.size > 0)
@@ -245,6 +265,9 @@ export function foldRecognizedMetadata(rendererName, file) {
                         hints.add(`prompt:${target.command.ref}`);
                     else
                         hints.add(`uses:${target.uses.ref}`);
+                    const used = target.uses.kind !== "builtin-command" ? target.uses.ref : storedCommandRef(target.command);
+                    if (used)
+                        out.uses = [used];
                 }
                 else {
                     hints.add(`run:${target.run}`);
@@ -321,6 +344,7 @@ export function foldRecognizedMetadata(rendererName, file) {
                     return out;
                 const plan = result.plan;
                 const hints = new Set();
+                const uses = new Set();
                 if (plan.preamble)
                     hints.add(plan.preamble);
                 for (const step of plan.steps) {
@@ -328,8 +352,13 @@ export function foldRecognizedMetadata(rendererName, file) {
                     hints.add(workflowStepInstructions(step));
                     if (step.gate.criteria[0])
                         hints.add(step.gate.criteria[0]);
+                    const used = workflowStepTarget(step.spec);
+                    if (used)
+                        uses.add(used);
                 }
                 out.searchHints = Array.from(hints).filter(Boolean);
+                if (uses.size > 0)
+                    out.uses = [...uses];
                 if (plan.paramSchemas) {
                     const parameters = Object.entries(plan.paramSchemas).map(([name, schema]) => {
                         const description = schema.description;
@@ -395,4 +424,6 @@ export function applyFoldedMetadata(entry, folded) {
         entry.toc = folded.toc;
     if (folded.parameters)
         entry.parameters = folded.parameters;
+    if (folded.uses)
+        entry.uses = folded.uses;
 }

package/dist/core/bundle-rename.js

@@ -30,7 +30,6 @@ import fs from "node:fs";
 import { readLockfile, renameLockEntry } from "../integrations/lockfile.js";
 import { closeDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
 import { getFilePathsByBundle, renameEntriesBundleId } from "../storage/repositories/index-entries-repository.js";
-import { renameLlmCacheAssetRefs } from "../storage/repositories/index-llm-cache-repository.js";
 import { countProposalsForBundleRename, renameProposalsBundleRef } from "../storage/repositories/proposals-repository.js";
 import { countTaskHistoryTargetRefs, renameTaskHistoryTargetRefs, } from "../storage/repositories/task-history-repository.js";
 import { selectBackend } from "../tasks/backends/index.js";
@@ -243,18 +242,13 @@ export async function renameBundle(oldId, newId, options = {}, deps) {
     // e.g. a plain filesystem bundle).
     await renameLockEntry(oldId, newId);
     // Index: bundle_id/item_ref on every entry row (see index-entries-repository's
-    // renameEntriesBundleId docstring for why no FTS/vector rebuild is needed),
-    // and the metadata-enrichment LLM cache keyed by the same canonical
-    // item_ref — in the SAME write, so a rename can never land between the two
-    // and leave the cache stranded under the old prefix (the next `akm index`'s
-    // clearStaleCacheEntries would then delete it, forcing a full re-enrich).
+    // renameEntriesBundleId docstring for why no FTS/vector rebuild is needed).
     const readIndexDb = openReadonlyExistingDatabase(getDbPath());
     if (readIndexDb) {
         closeDatabase(readIndexDb);
         const writeIndexDb = openIndexDatabase(getDbPath());
         try {
             renameEntriesBundleId(writeIndexDb, oldId, newId);
-            renameLlmCacheAssetRefs(writeIndexDb, oldId, newId);
         }
         finally {
             closeDatabase(writeIndexDb);

package/dist/core/config/config-schema.js

@@ -60,7 +60,7 @@ export { EngineConfigSchema, EnginesSchema, LlmConnectionConfigSchema, LlmProfil
 export { ExperimentalConfigSchema } from "./schema/experimental.js";
 export { FEEDBACK_FAILURE_MODES, FeedbackConfigSchema } from "./schema/feedback.js";
 export { ImproveConfigSchema } from "./schema/improve.js";
-export { ConsolidateProcessConfigSchema, DistillProcessConfigSchema, ExtractProcessConfigSchema, GraphExtractionProcessConfigSchema, ImproveProcessConfigSchema, ImproveProfileConfigSchema, MemoryInferenceProcessConfigSchema, ProactiveMaintenanceProcessConfigSchema, ReflectProcessConfigSchema, TriageProcessConfigSchema, ValidationProcessConfigSchema, } from "./schema/improve-processes.js";
+export { ConsolidateProcessConfigSchema, DistillProcessConfigSchema, ExtractProcessConfigSchema, ImproveProcessConfigSchema, ImproveProfileConfigSchema, MemoryInferenceProcessConfigSchema, ProactiveMaintenanceProcessConfigSchema, ReflectProcessConfigSchema, TriageProcessConfigSchema, ValidationProcessConfigSchema, } from "./schema/improve-processes.js";
 export { IndexConfigSchema, IndexPassConfigSchema } from "./schema/index-config.js";
 export { OutputConfigSchema } from "./schema/output.js";
 export { CURRENT_CONFIG_VERSION, LlmInvocationOverridesSchema } from "./schema/primitives.js";
@@ -240,6 +240,13 @@ export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) =>
     }
     const defaultStrategy = config.defaults?.improveStrategy;
     if (defaultStrategy &&
+        // graph-refresh is exempt from this eager, config-load-time check: unlike
+        // a plain typo, it is a specific, known retirement, and refusing it here
+        // would fail every command's config load (including `akm migrate apply`,
+        // the one that fixes this). `resolveImproveStrategy`
+        // (src/commands/improve/improve-strategies.ts) refuses it lazily, at
+        // improve-invocation time, with the same message either way.
+        defaultStrategy !== "graph-refresh" &&
         !BUILTIN_IMPROVE_STRATEGY_NAMES.includes(defaultStrategy) &&
         !config.improve?.strategies?.[defaultStrategy]) {
         ctx.addIssue({

package/dist/core/config/config.js

@@ -27,36 +27,6 @@ export { VALID_HARNESS_IDS } from "./config-types.js";
 // Canonical taxonomy lives in the schema/validator layer; re-exported here so
 // existing `../core/config/config` import sites keep working.
 export { FEEDBACK_FAILURE_MODES } from "./config-schema.js";
-/**
- * Default value for {@link IndexPassConfig.graphExtractionBatchSize}. Chosen
- * empirically: 4 amortises the per-call HTTP overhead 4× while keeping the
- * combined prompt size well under common 8K/16K context windows (each body is
- * sliced to ~500 chars in the graph-extract prompt builder).
- */
-const DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE = 4;
-/**
- * Approximate character budget per asset body inside a batched
- * graph-extraction prompt — used by {@link resolveBatchSize} to derive a
- * context-window ceiling when `llm.contextLength` is configured. This accounts
- * for the actual `MAX_BODY_CHARS` (500) in graph-extract.ts plus the system
- * prompt, user prompt wrapper, and expected JSON response overhead.
- */
-const GRAPH_EXTRACTION_CHARS_PER_BODY = 1500;
-/**
- * Clamp a configured batch size against the model's known context window.
- *
- * `configured` defaults to {@link DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE} when
- * `undefined`. When `contextLength` is provided, the result is the smaller of
- * `configured` and `floor(contextLength / GRAPH_EXTRACTION_CHARS_PER_BODY)`,
- * with a floor of 1 so the batched path always processes at least one body.
- */
-export function resolveBatchSize(configured, contextLength) {
-    const base = configured && configured > 0 ? configured : DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE;
-    if (!contextLength || contextLength <= 0)
-        return base;
-    const ceiling = Math.max(1, Math.floor(contextLength / GRAPH_EXTRACTION_CHARS_PER_BODY));
-    return Math.max(1, Math.min(base, ceiling));
-}
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
     configVersion: "0.9.0",
@@ -210,6 +180,18 @@ function buildEffectiveConfig(liftedLocalRaw, sourcePath) {
     assertUniquePhysicalBundleRoots(finalResult.data, sourcePath);
     return finalResult.data;
 }
+/**
+ * Retired `index.<passName>` keys that still validate against the generic
+ * per-pass catchall schema (`IndexPassConfigSchema`), so `resolveSchemaAt`
+ * below never returns `undefined` for them and the walk would otherwise
+ * treat them as a live, ordinary pass. Named here so the same three
+ * guarantees apply as any other retired config key (AGENTS.md "Reading
+ * persisted data"): a config setting one keeps loading, is named once by
+ * the unknown-key warning, and is dropped only by `akm migrate apply`.
+ * Both were retired in 0.9.17-alpha.9: `index.graph` (the LLM entity-graph
+ * extraction pass) and `index.metadataEnhance` (LLM metadata enrichment).
+ */
+const RETIRED_CATCHALL_KEY_PATHS = new Set(["index.graph", "index.metadataEnhance"]);
 /**
  * Every dotted key in `raw` the schema does not know, at any depth (arrays
  * are not descended). Unknown keys are never an error: they are a typo, or a
@@ -221,7 +203,7 @@ export function unknownConfigKeyPaths(root, node = root, prefix = []) {
     const found = [];
     for (const key of Object.keys(node).sort()) {
         const keyPath = [...prefix, key];
-        if (resolveSchemaAt(keyPath, root) === undefined) {
+        if (RETIRED_CATCHALL_KEY_PATHS.has(keyPath.join(".")) || resolveSchemaAt(keyPath, root) === undefined) {
             found.push(keyPath);
             continue;
         }
@@ -695,6 +677,16 @@ export function normalizeConfigFile(configPath, options) {
         const body = withSchedulerOnDisk(configWriteBody(localRaw, current, next), next);
         for (const keyPath of unknownConfigKeyPaths(body))
             deleteConfigPath(body, keyPath);
+        // `improve.strategies["graph-refresh"]` is schema-valid (any name is a
+        // legal custom-strategy key), so it never reaches the unknown-key sweep
+        // above. It can only be a leftover override of the deleted graph-refresh
+        // built-in (0.9.17-alpha.9) — resolveImproveStrategy now refuses that
+        // name unconditionally, so the override can never apply again. Drop it
+        // the same way any other retired key is dropped: only by `akm migrate
+        // apply`, never by an ordinary write.
+        const strategies = body.improve?.strategies;
+        if (strategies && Object.hasOwn(strategies, "graph-refresh"))
+            delete strategies["graph-refresh"];
         const keys = [...new Set([...Object.keys(raw), ...Object.keys(body)])]
             .filter((key) => JSON.stringify(raw[key]) !== JSON.stringify(body[key]))
             .sort();
@@ -928,23 +920,6 @@ export function resolveSecret(value, resolveFromStore) {
         return resolved ?? "";
     });
 }
-/**
- * Read a per-pass {@link IndexPassConfig} entry from {@link IndexConfig},
- * filtering out the reserved feature-section keys so callers don't mistake
- * `metadataEnhance` for a pass.
- */
-/** Reserved well-known keys on IndexConfig that are NOT per-pass entries. */
-const INDEX_RESERVED_KEYS = new Set(["metadataEnhance"]);
-export function getIndexPassConfig(config, passName) {
-    if (!config)
-        return undefined;
-    if (INDEX_RESERVED_KEYS.has(passName))
-        return undefined;
-    const entry = config[passName];
-    if (!entry || typeof entry !== "object")
-        return undefined;
-    return entry;
-}
 // Re-export source runtime helpers — implementation lives in config-sources.ts.
 export { bundleComponentConfig, bundleContentRoot, bundleContentRoots, bundleEntryToSourceEntry, bundleKeyForContentRoot, bundlePhysicalContentRoot, bundleSourceId, bundlesToSourceEntries, installedSourceDescriptor, isBundleEnabled, parseSourceSpec, primaryBundlePath, resolveActiveConfiguredSources, resolveConfiguredSources, } from "./config-sources.js";
 /**

package/dist/core/config/engine-semantics.js

@@ -6,7 +6,6 @@ export const BUILTIN_IMPROVE_STRATEGY_NAMES = [
     "default",
     "quick",
     "thorough",
-    "graph-refresh",
     "consolidate",
     "catchup",
     "reflect-distill",
@@ -18,7 +17,6 @@ export const IMPROVE_PROCESS_ENGINE_CAPABILITIES = {
     distill: "llm",
     consolidate: "llm",
     memoryInference: "llm",
-    graphExtraction: "llm",
     extract: "llm",
     validation: "llm",
     triage: "runner",

package/dist/core/config/schema/improve-processes.js

@@ -10,13 +10,14 @@ import { IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "../engine-semantics.js";
 import { engineName, LlmInvocationOverridesSchema, nonEmptyString, positiveInt } from "./primitives.js";
 // ── Improve profile / process ──────────────────────────────────────────────
 //
-// WI-9.6 (§4.2/§10.2): each of the 9 improve processes (reflect, distill,
-// consolidate, memoryInference, graphExtraction, extract, validation, triage,
-// proactiveMaintenance) gets its OWN schema below — a shared base (engine,
-// model, llm, enabled, timeoutMs) extended with only the fields meaningful on
-// that process — replacing the prior single ImproveProcessConfigSchema reused
-// via `.optional()` for all 9 keys (which accepted, and silently ignored, any
-// field on any process). Field→process assignment is derived from each
+// WI-9.6 (§4.2/§10.2): each of the improve processes (reflect, distill,
+// consolidate, memoryInference, extract, validation, triage,
+// proactiveMaintenance — graphExtraction had one too, until the LLM
+// entity-graph it ran was retired in 0.9.17-alpha.9) gets its OWN schema
+// below — a shared base (engine, model, llm, enabled, timeoutMs) extended
+// with only the fields meaningful on that process — replacing the prior
+// single ImproveProcessConfigSchema reused via `.optional()` for all of them
+// (which accepted, and silently ignored, any field on any process). Field→process assignment is derived from each
 // field's original "only meaningful on X" doc comment, cross-checked against
 // its actual runtime consumers and the built-in strategy assets
 // (src/assets/improve-strategies/*.json).
@@ -164,12 +165,6 @@ const CONSOLIDATE_PROCESS_FIELDS = {
     // entirely (emits `pool_below_min_size`). 0 disables the guard. Default 500.
     minPoolSize: z.number().int().min(0).optional(),
     maxChunkSize: z.number().int().min(1).max(50).optional(),
-    // Narrow candidate pool to memories modified within this duration window
-    // plus their graph neighbours. Absent = full-pool sweep.
-    incrementalSince: z.string().optional(),
-    // Graph neighbours per changed memory during incremental consolidation.
-    // Default 5. Only meaningful with incrementalSince.
-    neighborsPerChanged: z.number().int().min(1).optional(),
     // Fallback p90 wall-clock time per consolidation chunk in seconds, used for
     // cold-start budget estimation when no telemetry history exists. The actual
     // p90 is derived from observed run durations once sufficient history
@@ -182,29 +177,6 @@ const MEMORY_INFERENCE_PROCESS_FIELDS = {
     minPendingCount: z.number().int().min(0).optional(),
     cls: clsField,
 };
-/**
- * GraphExtraction process fields: one strategy's graph extraction scope and
- * batching. `includeTypes` and `batchSize` override `index.graph`'s
- * `graphExtractionIncludeTypes` and `graphExtractionBatchSize`; unset, the
- * pass reads those.
- */
-const GRAPH_EXTRACTION_PROCESS_FIELDS = {
-    // #624 P2: when set, rank eligible files by utility_scores DESC and process
-    // only the top-N per run (incremental high-signal-first sweep). Unset =
-    // process all eligible (current behavior).
-    topN: positiveInt.optional(),
-    includeTypes: z.array(z.string().min(1)).min(1).optional(),
-    batchSize: positiveInt.optional(),
-    // Full-corpus scan. When true, graph extraction runs on ALL stash files
-    // instead of only files touched by actionable refs in the current run.
-    // Used by the `graph-refresh` built-in profile / a scheduled weekly task.
-    fullScan: z.boolean().optional(),
-    // R12b + R20: cap on chunks processed per asset. A body chunked beyond this
-    // is truncated to the first N chunks instead of paying for unbounded
-    // per-asset LLM calls; the coverage loss is recorded as truncatedChunks.
-    // Absent = default 8 (src/llm/graph-extract.ts DEFAULT_MAX_CHUNKS_PER_ASSET).
-    maxChunksPerAsset: positiveInt.optional(),
-};
 const EXTRACT_PROCESS_FIELDS = {
     defaultSince: z.string().min(1).optional(),
     maxTotalChars: positiveInt.optional(),
@@ -264,7 +236,6 @@ export const ImproveProcessConfigSchema = z
     ...DISTILL_PROCESS_FIELDS,
     ...CONSOLIDATE_PROCESS_FIELDS,
     ...MEMORY_INFERENCE_PROCESS_FIELDS,
-    ...GRAPH_EXTRACTION_PROCESS_FIELDS,
     ...EXTRACT_PROCESS_FIELDS,
     ...TRIAGE_PROCESS_FIELDS,
     ...PROACTIVE_MAINTENANCE_PROCESS_FIELDS,
@@ -288,10 +259,6 @@ export const ConsolidateProcessConfigSchema = z
 export const MemoryInferenceProcessConfigSchema = z
     .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...MEMORY_INFERENCE_PROCESS_FIELDS })
     .passthrough();
-/** `processes.graphExtraction` — narrow per-process schema (WI-9.6). */
-export const GraphExtractionProcessConfigSchema = z
-    .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...GRAPH_EXTRACTION_PROCESS_FIELDS })
-    .passthrough();
 /** `processes.extract` — narrow per-process schema (WI-9.6). */
 export const ExtractProcessConfigSchema = z
     .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...EXTRACT_PROCESS_FIELDS })
@@ -306,13 +273,20 @@ export const TriageProcessConfigSchema = z
 export const ProactiveMaintenanceProcessConfigSchema = z
     .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...PROACTIVE_MAINTENANCE_PROCESS_FIELDS })
     .passthrough();
+/**
+ * Process names that once had a dedicated schema and are now gone. Setting
+ * one, even with `enabled: true`, is tolerated rather than rejected by the
+ * "unknown enabled process" check below — an old config must keep loading
+ * (AGENTS.md "Reading persisted data"). `graphExtraction`: the LLM
+ * entity-graph extraction it ran was retired in 0.9.17-alpha.9.
+ */
+const RETIRED_PROCESS_NAMES = new Set(["graphExtraction"]);
 const ImproveProfileProcessesSchema = z
     .object({
     reflect: ReflectProcessConfigSchema.optional(),
     distill: DistillProcessConfigSchema.optional(),
     consolidate: ConsolidateProcessConfigSchema.optional(),
     memoryInference: MemoryInferenceProcessConfigSchema.optional(),
-    graphExtraction: GraphExtractionProcessConfigSchema.optional(),
     extract: ExtractProcessConfigSchema.optional(),
     validation: ValidationProcessConfigSchema.optional(),
     triage: TriageProcessConfigSchema.optional(),
@@ -335,6 +309,7 @@ const ImproveProfileProcessesSchema = z
     }
     for (const [name, process] of Object.entries(val)) {
         if (!(name in IMPROVE_PROCESS_ENGINE_CAPABILITIES) &&
+            !RETIRED_PROCESS_NAMES.has(name) &&
             process !== null &&
             typeof process === "object" &&
             process.enabled === true) {