akm-cli 0.9.16 → 0.9.17-alpha.2

package/dist/commands/proposal/repository.js

@@ -43,7 +43,7 @@ import { ensureAkmMarkdownType } from "../../core/asset/akm-markdown.js";
 import { assetPathForName, placementTypes, stashDirFor } from "../../core/asset/asset-placement.js";
 import { isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { assembleAsset, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
-import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { carryForwardBookkeepingFrontmatter, computeNormalizedContentHash, parseFrontmatter, } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { isWithin } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
@@ -66,7 +66,7 @@ import { openSqliteReadSnapshot } from "../../storage/sqlite-read-snapshot.js";
 import { pkgVersion } from "../../version.js";
 import { runBaseChecks } from "../lint/base-linter.js";
 import { formatNewAssetDiff, formatUnifiedDiff } from "./diff-format.js";
-import { isAutomatedProposalSource, isValidProposalSource, PROPOSAL_SOURCES, } from "./proposal-types.js";
+import { isAutomatedProposalSource, isStaleTargetRejection, isValidProposalSource, PROPOSAL_SOURCES, } from "./proposal-types.js";
 import { canonicalOnlyProposalValidators, hasCanonicalProposalValidator, runProposalValidators, } from "./validators/proposal-validators.js";
 import { repairProposalContent, validateProposal } from "./validators/proposals.js";
 const PROMOTION_LINT_ISSUE_TYPES = new Set(["unquoted-colon", "missing-ref", "stale-path"]);
@@ -241,6 +241,40 @@ export function resolveProposalQueueTarget(stashDir, config = loadConfig()) {
     }
     return { source: bundleId, root };
 }
+/**
+ * Resolve the durable target ref, target root/rel-path, and current
+ * before-hash for a parsed proposal ref (WI-6.2). This is the exact
+ * computation `createProposal` uses to derive its mint-time `beforeHash`
+ * fingerprint term; {@link checkProposalGuard} (R9) calls it too, so a
+ * pre-generation guard check and `createProposal`'s post-generation check
+ * always agree on what "these inputs" means for the same ref/target.
+ */
+function resolveProposalTargetInfo(stashDir, parsedRef, explicitTarget) {
+    const proposalTarget = resolveCreateProposalTarget(stashDir, explicitTarget, parsedRef.origin);
+    const normalizedRef = proposalDurableRef(parsedRef, proposalTarget);
+    const targetRoot = path.resolve(proposalTarget.root);
+    let targetRelPath;
+    let mintBeforeContent;
+    try {
+        const typeRoot = path.join(targetRoot, stashDirFor(parsedRef.type));
+        const targetAbs = assetPathForName(parsedRef.type, typeRoot, parsedRef.name);
+        targetRelPath = path.relative(targetRoot, targetAbs);
+        if (fs.existsSync(targetAbs))
+            mintBeforeContent = fs.readFileSync(targetAbs, "utf8");
+    }
+    catch {
+        // Resolution failure degrades to a best-effort create — never blocks the mint.
+        targetRelPath = path.join(stashDirFor(parsedRef.type), parsedRef.name);
+    }
+    return {
+        proposalTarget,
+        normalizedRef,
+        targetRoot,
+        targetRelPath,
+        beforeHash: mintBeforeContent !== undefined ? contentHash(mintBeforeContent) : undefined,
+        beforeHashNormalized: mintBeforeContent !== undefined ? computeNormalizedContentHash(mintBeforeContent) : undefined,
+    };
+}
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
  * Create a new pending proposal. The id is a stable random UUID, so two
@@ -310,27 +344,12 @@ export function createProposal(stashDir, input, ctx) {
             return rejectProposal("missing_description", `Proposal for "${input.ref}" (source=consolidate) has empty or missing frontmatter description.`);
         }
     }
-    const proposalTarget = resolveCreateProposalTarget(stashDir, input.target, parsedRef.origin);
-    const normalizedRef = proposalDurableRef(parsedRef, proposalTarget);
-    const targetRoot = path.resolve(proposalTarget.root);
     // WI-6.2: derive the FileChange[] envelope + mint-time beforeHash. The
     // target is resolved against the proposal's OWN stash (a local snapshot —
     // accept re-resolves the write target from config at apply time), and only
     // the before-state's HASH is kept: the change's `before` body is a
     // transaction-time capture that does not exist at mint time.
-    let targetRelPath;
-    let mintBeforeContent;
-    try {
-        const typeRoot = path.join(targetRoot, stashDirFor(parsedRef.type));
-        const targetAbs = assetPathForName(parsedRef.type, typeRoot, parsedRef.name);
-        targetRelPath = path.relative(targetRoot, targetAbs);
-        if (fs.existsSync(targetAbs))
-            mintBeforeContent = fs.readFileSync(targetAbs, "utf8");
-    }
-    catch {
-        // Resolution failure degrades to a best-effort create — never blocks the mint.
-        targetRelPath = path.join(stashDirFor(parsedRef.type), parsedRef.name);
-    }
+    const { proposalTarget, normalizedRef, targetRoot, targetRelPath, beforeHash: mintedBeforeHash, beforeHashNormalized: mintedBeforeHashNormalized, } = resolveProposalTargetInfo(stashDir, parsedRef, input.target);
     const proposalContent = targetRelPath.toLowerCase().endsWith(".md")
         ? ensureAkmMarkdownType(input.payload.content, parsedRef.type)
         : input.payload.content;
@@ -338,10 +357,9 @@ export function createProposal(stashDir, input, ctx) {
         {
             path: targetRelPath,
             after: proposalContent,
-            op: mintBeforeContent !== undefined ? "update" : "create",
+            op: mintedBeforeHash !== undefined ? "update" : "create",
         },
     ];
-    const mintedBeforeHash = mintBeforeContent !== undefined ? contentHash(mintBeforeContent) : undefined;
     if (hasCanonicalProposalValidator(parsedRef.type)) {
         // Mint-time gate: structural shape only (generic + canonical-per-type),
         // NOT the full quality-validator list — see canonicalOnlyProposalValidators'
@@ -374,7 +392,7 @@ export function createProposal(stashDir, input, ctx) {
     return withProposalsDb(stashDir, ctx, (db) => {
         return withImmediateTransaction(db, () => {
             if (!input.force) {
-                const skip = checkFingerprintAndBackoff(db, stashDir, normalizedRef, input, fingerprint, ctx);
+                const skip = checkFingerprintAndBackoff(db, stashDir, normalizedRef, input.source, fingerprint, ctx);
                 if (skip)
                     return skip;
             }
@@ -403,6 +421,7 @@ export function createProposal(stashDir, input, ctx) {
                 changes: mintedChanges,
                 proposedTarget: { source: proposalTarget.source, root: targetRoot },
                 ...(mintedBeforeHash !== undefined ? { beforeHash: mintedBeforeHash } : {}),
+                ...(mintedBeforeHashNormalized !== undefined ? { beforeHashNormalized: mintedBeforeHashNormalized } : {}),
                 ...(sanitizedConfidence !== undefined ? { confidence: sanitizedConfidence } : {}),
                 // Attribution tagging: persist the eligibility lane so it survives to
                 // accept/reject/revert time. See EligibilitySource.
@@ -455,9 +474,9 @@ function recordProposalFingerprint(db, stashDir, fingerprint, ref, input, propos
  * Evaluate the fingerprint + rejection-backoff guards. Returns the skip
  * record when a guard fires, or undefined when the create may proceed.
  */
-function checkFingerprintAndBackoff(db, stashDir, normalizedRef, input, fingerprint, ctx) {
+function checkFingerprintAndBackoff(db, stashDir, normalizedRef, source, fingerprint, ctx) {
     const nowMs = (ctx?.now ?? Date.now)();
-    const backoffMs = cooldownMsForSource(input.source);
+    const backoffMs = cooldownMsForSource(source);
     // §23.6: an already-processed fingerprint skips another model call's output
     // unless explicitly forced. The row survives the proposal's lifecycle —
     // identical inputs stay deduplicated until the target (before-hash), the
@@ -474,9 +493,13 @@ function checkFingerprintAndBackoff(db, stashDir, normalizedRef, input, fingerpr
         };
     }
     // Rejection backoff (RETAINED cooldown semantics): a recent rejection for
-    // this ref+source suppresses new proposals until the window expires.
+    // this ref+source suppresses new proposals until the window expires. A
+    // stale-target auto-reject (STALE, R20) is excluded — it is not a
+    // judgement on the content, and counting it here would suppress a
+    // legitimate re-propose against the ref's now-current content.
     const rejected = listStateProposals(db, { stashDir, ref: normalizedRef, status: "rejected" })
-        .filter((p) => p.source === input.source)
+        .filter((p) => p.source === source)
+        .filter((p) => !isStaleTargetRejection(p))
         .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime());
     const mostRecent = rejected[0];
     if (mostRecent !== undefined) {
@@ -487,7 +510,7 @@ function checkFingerprintAndBackoff(db, stashDir, normalizedRef, input, fingerpr
             return {
                 skipped: true,
                 reason: "rejection_backoff",
-                message: `Proposal for ${normalizedRef} from source "${input.source}" is in rejection backoff ` +
+                message: `Proposal for ${normalizedRef} from source "${source}" is in rejection backoff ` +
                     `(${backoffDays}d window, ~${remainingDays}d remaining). Pass force:true to bypass.`,
                 existingProposalId: mostRecent.id,
             };
@@ -495,6 +518,36 @@ function checkFingerprintAndBackoff(db, stashDir, normalizedRef, input, fingerpr
     }
     return undefined;
 }
+/**
+ * R9 (tier2-0917): pure pre-generation check of the fingerprint-match /
+ * rejection-backoff guard — the same computation `createProposal` runs AFTER
+ * generation (`checkFingerprintAndBackoff`), exposed so a caller can skip an
+ * expensive LLM call BEFORE making it. Shares {@link resolveProposalTargetInfo}
+ * and {@link checkFingerprintAndBackoff} verbatim with `createProposal`, so
+ * the two can never disagree about what "these inputs" means for the same
+ * ref/source/target/model. `createProposal`'s post-generation check remains
+ * the authoritative gate: this is a best-effort optimisation that fails open
+ * (returns `undefined`, i.e. "not skipped") on any resolution error — an
+ * unresolvable target here must never block the real dispatch.
+ */
+export function checkProposalGuard(input, ctx) {
+    try {
+        const parsedRef = parseRefInput(input.ref);
+        if (!stashDirFor(parsedRef.type))
+            return undefined;
+        const { normalizedRef, beforeHash } = resolveProposalTargetInfo(input.stash, parsedRef, input.target);
+        const fingerprint = computeProposalFingerprint({
+            ref: normalizedRef,
+            source: input.source,
+            ...(beforeHash !== undefined ? { beforeHash } : {}),
+            ...(input.modelId !== undefined ? { modelId: input.modelId } : {}),
+        });
+        return withProposalsDb(input.stash, ctx, (db) => checkFingerprintAndBackoff(db, input.stash, normalizedRef, input.source, fingerprint, ctx));
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * List proposals for one stash. By default returns only the live (pending)
  * queue; pass `{ includeArchive: true }` to include accepted / rejected /
@@ -1571,9 +1624,24 @@ export function preflightProposalPromotion(config, proposal, options = {}, ctx)
     if (!assetPath)
         throw new UsageError(`Cannot resolve proposal target ${preparedProposal.ref}.`, "INVALID_PROPOSAL");
     assertAkmAssetWrite(target.source);
-    const stampedContent = assetPath.toLowerCase().endsWith(".md")
+    let stampedContent = assetPath.toLowerCase().endsWith(".md")
         ? stampProposalProvenance(repairedContent, preparedProposal, options.gateDecision, ctx, nowIso(ctx))
         : repairedContent;
+    if (assetPath.toLowerCase().endsWith(".md") && fs.existsSync(assetPath)) {
+        // STALE (R20): carry the live target's akm bookkeeping frontmatter
+        // forward when the proposal's own frontmatter doesn't set it, so
+        // promoting never drops e.g. `inferenceProcessed` and makes memory
+        // inference reprocess the memory. Best-effort — an unreadable live file
+        // here doesn't block promotion; the freshness guard below is the real
+        // gate on staleness.
+        try {
+            const liveRaw = fs.readFileSync(assetPath, "utf8");
+            stampedContent = carryForwardBookkeepingFrontmatter(stampedContent, liveRaw);
+        }
+        catch {
+            // Best-effort — see comment above.
+        }
+    }
     const lintBlockers = promotionLintBlockers(stampedContent, assetPath, target.source.path, ref.type, config);
     if (lintBlockers.length > 0) {
         const summary = lintBlockers.map((finding) => `[${finding.issue}] ${finding.detail}`).join("; ");
@@ -1707,8 +1775,19 @@ async function promoteProposalWithLease(stashDir, config, id, options, ctx) {
             throw new Error(`Proposal backup read failed for ${assetPath}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    if (proposal.beforeHash !== undefined && (!backup || proposalHash(backup) !== proposal.beforeHash)) {
-        throw new UsageError(`Proposal target changed after proposal ${id} was created; refusing to overwrite newer content.`, "INVALID_FLAG_VALUE");
+    if (proposal.beforeHash !== undefined) {
+        // STALE (R20): a proposal minted with a normalized before-hash is fresh
+        // when the CURRENT target's bookkeeping-stripped content still matches —
+        // insensitive to a same-run bookkeeping rewrite (salience scoring,
+        // inference dedup marking) of the target after mint. A legacy proposal
+        // without one keeps the exact raw-hash check it always had.
+        const fresh = proposal.beforeHashNormalized !== undefined
+            ? backup !== undefined &&
+                computeNormalizedContentHash(backup.toString("utf8")) === proposal.beforeHashNormalized
+            : backup !== undefined && proposalHash(backup) === proposal.beforeHash;
+        if (!fresh) {
+            throw new UsageError(`Proposal target changed after proposal ${id} was created; refusing to overwrite newer content.`, "INVALID_FLAG_VALUE");
+        }
     }
     if (proposal.beforeHash === undefined &&
         backup !== undefined &&

package/dist/commands/tasks/tasks.js

@@ -23,7 +23,7 @@ import { IMPROVE_AUTONOMY_CONFIG_KEY, isImproveAutonomyEnabled } from "../../cor
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
-import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetForMutation, resolveWorkingStashTarget, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { commitWriteTargetBoundary, deleteAssetFromSource, isWriteCapableSourceKind, prepareWriteTargetForMutation, resolveWorkingStashTarget, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
 import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
 import { activeSchedulerActivations, isSchedulerRefEnabled, setSchedulerRefEnabled, } from "../../tasks/activation-config.js";
@@ -411,7 +411,24 @@ async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
     const nativeArtifacts = inspection.artifacts;
     const configuredSources = resolveConfiguredSources(config);
     const activeSources = resolveActiveConfiguredSources(config);
-    const sourceNames = bundleTarget ? [bundleTarget] : activeSources.map((source) => source.name);
+    if (bundleTarget) {
+        // adaptConfiguredSource (src/core/write-source.ts) rejects any kind
+        // other than filesystem/git outright, so a website/npm bundle can never
+        // carry scheduler state (akm task enable already fails the same way).
+        // Surface that as a clear usage error here instead of letting the
+        // write-target resolution below raise a generic ConfigError.
+        const targetSource = activeSources.find((source) => source.name === bundleTarget);
+        if (targetSource && !isWriteCapableSourceKind(targetSource.type)) {
+            throw new UsageError(`Bundle "${bundleTarget}" has kind "${targetSource.type}"; task scheduling is only supported for filesystem and git bundles.`, "INVALID_FLAG_VALUE");
+        }
+    }
+    // Unscoped sync only installs/removes bindings for bundles that can carry
+    // them (filesystem/git). A website/npm bundle contributes no installs and
+    // must not crash the loop; inactiveOperations below still sees it via
+    // configuredSources for removal/revocation.
+    const sourceNames = bundleTarget
+        ? [bundleTarget]
+        : activeSources.filter((source) => isWriteCapableSourceKind(source.type)).map((source) => source.name);
     const inactiveOperations = bundleTarget
         ? []
         : inactiveBundleRemovalOperations(config, configuredSources, allEntries, nativeArtifacts);

package/dist/core/asset/frontmatter.js

@@ -8,11 +8,12 @@
  * (block scalars, multi-line strings, nested objects, flow sequences, escape
  * sequences) is handled correctly without a brittle hand-rolled state machine.
  */
+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 { recordWrittenPath } from "../write-provenance.js";
-import { assembleAsset, serializeFrontmatter } from "./asset-serialize.js";
+import { assembleAsset, assembleAssetFromString, serializeFrontmatter } from "./asset-serialize.js";
 /**
  * Parse YAML frontmatter from a Markdown (or similar) string.
  *
@@ -451,6 +452,110 @@ export function parseYamlScalar(value) {
     }
     return value;
 }
+// ── Bookkeeping-insensitive freshness (STALE, R20) ────────────────────────────
+/**
+ * Frontmatter keys akm's own improve/index passes write into an EXISTING
+ * asset as pipeline bookkeeping — never a change to the asset's authored
+ * meaning. `salience`/`salienceInputs` come from {@link writeSalienceToFrontmatter}
+ * (distill); `inferenceProcessed` comes from memory inference
+ * (`indexer/passes/memory-inference.ts`). A pending proposal's mint-time
+ * before-hash is sensitive to these rewrites even though nothing a reviewer
+ * or the proposal's own diff cares about actually changed, which stales out
+ * proposals that a same-run bookkeeping pass touches after mint. See
+ * {@link computeNormalizedContentHash} and {@link carryForwardBookkeepingFrontmatter}.
+ *
+ * Deliberately excludes `beliefState`/`contradictedBy`/`supersededBy`: those
+ * are editorial state (contradiction/supersession demotions), not derived
+ * audit metadata — a promote should still refuse when one of those changed
+ * underneath a pending proposal.
+ */
+export const BOOKKEEPING_FRONTMATTER_KEYS = ["salience", "salienceInputs", "inferenceProcessed"];
+function sha256Hex(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/**
+ * Hash of `raw` with {@link BOOKKEEPING_FRONTMATTER_KEYS} removed from its
+ * frontmatter and the remaining frontmatter re-serialized with sorted keys,
+ * so pipeline-only bookkeeping rewrites (and incidental key-order churn)
+ * cannot change the result. The body's boundary is normalized the same way
+ * {@link assembleAssetFromString} normalizes it (leading newlines stripped,
+ * exactly one trailing newline) before hashing, so the body-boundary shift
+ * that `writeSalienceToFrontmatter` and the `assembleAsset` bookkeeping
+ * rewrite both introduce cannot change the result either; the body's
+ * interior is still hashed verbatim.
+ *
+ * An empty frontmatter block (`---\n---\n…`) is treated as `{}` rather than
+ * falling back to the raw hash, so adding bookkeeping keys to a memory with
+ * no prior frontmatter fields is still insensitive.
+ *
+ * Falls back to hashing `raw` verbatim when there is no frontmatter block at
+ * all or it fails to parse — normalizing unparsable frontmatter isn't safe,
+ * and the caller's existing raw-hash check already covers that case.
+ */
+export function computeNormalizedContentHash(raw) {
+    const block = parseFrontmatterBlock(raw);
+    if (!block)
+        return sha256Hex(raw);
+    let data;
+    try {
+        data = block.frontmatter.trim() ? yamlParse(block.frontmatter) : {};
+    }
+    catch {
+        return sha256Hex(raw);
+    }
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        return sha256Hex(raw);
+    const normalized = { ...data };
+    for (const key of BOOKKEEPING_FRONTMATTER_KEYS)
+        delete normalized[key];
+    const canonicalFrontmatter = yamlStringify(normalized, { sortMapEntries: true }).trimEnd();
+    return sha256Hex(assembleAssetFromString(canonicalFrontmatter, block.content));
+}
+/**
+ * Fold the live target's {@link BOOKKEEPING_FRONTMATTER_KEYS} into
+ * `proposedRaw` wherever the proposal's own frontmatter does not already set
+ * them, so promoting a proposal minted before a bookkeeping rewrite never
+ * drops that bookkeeping (STALE, R20) — e.g. dropping `inferenceProcessed`
+ * would make memory inference reprocess the memory.
+ *
+ * Returns `proposedRaw` unchanged when either side has no parseable
+ * frontmatter block or nothing needs to carry forward.
+ */
+export function carryForwardBookkeepingFrontmatter(proposedRaw, liveRaw) {
+    const proposedBlock = parseFrontmatterBlock(proposedRaw);
+    const liveBlock = parseFrontmatterBlock(liveRaw);
+    if (!proposedBlock || !liveBlock)
+        return proposedRaw;
+    let proposedData;
+    let liveData;
+    try {
+        const parsedProposed = proposedBlock.frontmatter.trim() ? yamlParse(proposedBlock.frontmatter) : {};
+        const parsedLive = liveBlock.frontmatter.trim() ? yamlParse(liveBlock.frontmatter) : {};
+        if (parsedProposed === null || typeof parsedProposed !== "object" || Array.isArray(parsedProposed)) {
+            return proposedRaw;
+        }
+        if (parsedLive === null || typeof parsedLive !== "object" || Array.isArray(parsedLive))
+            return proposedRaw;
+        proposedData = parsedProposed;
+        liveData = parsedLive;
+    }
+    catch {
+        return proposedRaw;
+    }
+    const merged = { ...proposedData };
+    let changed = false;
+    for (const key of BOOKKEEPING_FRONTMATTER_KEYS) {
+        if (!(key in merged) && key in liveData) {
+            merged[key] = liveData[key];
+            changed = true;
+        }
+    }
+    if (!changed)
+        return proposedRaw;
+    const newFrontmatter = yamlStringify(merged).trimEnd();
+    const separator = proposedBlock.content.startsWith("\n") ? "" : "\n";
+    return `---\n${newFrontmatter}\n---\n${separator}${proposedBlock.content}`;
+}
 // ── Minimum score delta to trigger a frontmatter salience rewrite ─────────────
 const SALIENCE_WRITE_DELTA_THRESHOLD = 0.05;
 /**

package/dist/core/config/config.js

@@ -16,6 +16,7 @@ import { bundleComponentConfig, bundleContentRoot, bundleContentRoots, bundlesTo
 import { upgradeConfigVersion } from "./config-version-shim.js";
 import { deepMergeConfig, isPlainObject } from "./deep-merge.js";
 import { migrateLegacySourceShape } from "./legacy-source-shape-shim.js";
+import { stripRetiredExperimentalKeys } from "./retired-experimental-keys-shim.js";
 import { isApiKeyReference, SECRET_STORE_REFERENCE_PATTERN } from "./schema/primitives.js";
 export { stripJsonComments } from "./config-io.js";
 import { getConfigPath } from "../paths.js";
@@ -147,7 +148,8 @@ export function acquireConfigReadFence() {
  * before it is either validated (the local/top-level file) or merged in as
  * an `extends` base: JSONC parse already done by the caller, then version
  * shim, then legacy `stashDir`/`sources[]`/`installed[]` shim, then the
- * legacy `extraParams` lift (#852). Shared by {@link parseAndValidateConfigText}
+ * legacy `extraParams` lift (#852), then the retired `experimental.*` key
+ * shim. Shared by {@link parseAndValidateConfigText}
  * (the local file) and {@link resolveExtendsChain} (each base in the chain) so
  * a fleet-shared base config can carry its own old `configVersion` / legacy
  * shape independently of the file that extends it.
@@ -155,7 +157,8 @@ export function acquireConfigReadFence() {
 function runConfigFilePipeline(text, sourcePath) {
     const versioned = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
     const parsedRaw = migrateLegacySourceShape(versioned, sourcePath);
-    return liftExtraParamsOrThrow(parsedRaw, sourcePath);
+    const liftedRaw = liftExtraParamsOrThrow(parsedRaw, sourcePath);
+    return stripRetiredExperimentalKeys(liftedRaw, sourcePath);
 }
 /**
  * #852 (following #815): a config still using legacy `extraParams` keys —

package/dist/core/config/retired-experimental-keys-shim.js

@@ -0,0 +1,62 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `experimental.*` retired-key shim.
+ *
+ * `ExperimentalConfigSchema` (`./schema/experimental.ts`) moved from
+ * `.passthrough()` to `.strict()` in 0.9.16 (`cc6152e02`) so a typo in an
+ * authority flag (e.g. `improveAutonomyy`) fails loudly instead of silently
+ * doing nothing. `workflowEngine` was removed from that block earlier, in
+ * `e0655d13c`, but 0.9.15's passthrough still accepted it — so a real config
+ * written by 0.9.15 can carry `experimental.workflowEngine` and now fails
+ * every command with `Invalid config: experimental: Unrecognized key(s)`.
+ *
+ * Per AGENTS.md "Reading persisted data": a reader tolerates what older
+ * releases wrote, converts in memory, warns once, and leaves the on-disk
+ * rewrite to `akm migrate apply`. This mirrors `./legacy-source-shape-shim.ts`
+ * exactly — strip the retired key(s) before schema validation, warn once
+ * naming the key and the migrate command — rather than reintroducing
+ * `.passthrough()`, which would also let a live key typo through silently.
+ */
+import { isRecord } from "../common.js";
+import { warnOnce } from "../warn.js";
+/**
+ * Every `experimental.*` key `ExperimentalConfigSchema` has ever retired.
+ * `workflowEngine` (removed in `e0655d13c`) is the only one so far — kept as
+ * a list because the shim and `akm migrate apply`
+ * (`scripts/akm-migrate/migrate/config-retired-experimental-keys.ts`) share
+ * it.
+ */
+export const RETIRED_EXPERIMENTAL_KEYS = ["workflowEngine"];
+/**
+ * Which `RETIRED_EXPERIMENTAL_KEYS` are present in a raw config's
+ * `experimental` section. Returns `[]` when `raw.experimental` is missing or
+ * not a record. Shared by `stripRetiredExperimentalKeys` below and by
+ * `akm migrate apply`'s on-disk counterpart
+ * (`scripts/akm-migrate/migrate/config-retired-experimental-keys.ts`).
+ */
+export function retiredExperimentalKeysIn(raw) {
+    const experimental = raw.experimental;
+    if (!isRecord(experimental))
+        return [];
+    return RETIRED_EXPERIMENTAL_KEYS.filter((key) => key in experimental);
+}
+/**
+ * Drop retired `experimental.*` keys from a raw parsed config object before
+ * schema validation, warning once per source when any were present. Live
+ * keys (including an unrecognized one, e.g. a typo) are left untouched for
+ * `ExperimentalConfigSchema.strict()` to reject as before.
+ */
+export function stripRetiredExperimentalKeys(raw, sourcePath) {
+    const present = retiredExperimentalKeysIn(raw);
+    if (present.length === 0)
+        return raw;
+    const original = raw.experimental;
+    const experimental = { ...original };
+    for (const key of present)
+        delete experimental[key];
+    const where = sourcePath ? ` at ${sourcePath}` : "";
+    warnOnce(`config:retired-experimental-key${sourcePath ? `:${sourcePath}` : ""}`, `Config${where} uses the retired experimental key(s) ${present.join(", ")} — ignored in memory. Run \`akm migrate apply\` to remove ${present.length === 1 ? "it" : "them"} from the config file and silence this warning.`);
+    return { ...raw, experimental };
+}

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

@@ -42,6 +42,15 @@ const IMPROVE_PROCESS_BASE_FIELDS = {
 };
 /** Reflect/distill/consolidate: process-level asset-type filter (see improve-strategies.ts shouldSkipRef/DEFAULT_ALLOWED_TYPES). */
 const allowedTypesField = z.array(z.string().min(1)).optional();
+/**
+ * Reflect only (R12): conceptId prefixes to exclude, matched after stripping
+ * an optional `bundle//` from both the ref and each prefix (see
+ * improve-strategies.ts shouldSkipRef). `allowedTypes` is type-only and can't
+ * exclude a subset of one type, e.g. raw wiki-ingest snapshots indexed as
+ * `knowledge/wikis/articles/raw/*`. distill/consolidate are memory-only and
+ * never read this field.
+ */
+const excludeRefPrefixesField = z.array(z.string().min(1)).optional();
 /**
  * Consolidate process: hard cap on memories processed per pass.
  * Reflect/distill: max refs processed (same as profile-level `limit`).
@@ -160,6 +169,7 @@ const antiCollapseField = z
     .optional();
 const REFLECT_PROCESS_FIELDS = {
     allowedTypes: allowedTypesField,
+    excludeRefPrefixes: excludeRefPrefixesField,
     limit: processLimitField,
     qualityGate: qualityGateField,
     lowValueFilter: lowValueFilterField,
@@ -215,6 +225,11 @@ const GRAPH_EXTRACTION_PROCESS_FIELDS = {
     // 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(),
@@ -293,6 +308,16 @@ function checkRetiredProcessKeys(value, ctx) {
         }
     }
 }
+/** distill/consolidate are memory-only and never read `excludeRefPrefixes` (reflect only, R12). */
+function rejectExcludeRefPrefixesOutsideReflect(value, ctx) {
+    if ("excludeRefPrefixes" in value) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["excludeRefPrefixes"],
+            message: "excludeRefPrefixes is only valid on the reflect process",
+        });
+    }
+}
 export const ImproveProcessConfigSchema = z
     .object({
     ...IMPROVE_PROCESS_BASE_FIELDS,
@@ -316,12 +341,14 @@ export const ReflectProcessConfigSchema = z
 export const DistillProcessConfigSchema = z
     .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...DISTILL_PROCESS_FIELDS })
     .passthrough()
-    .superRefine(checkRetiredProcessKeys);
+    .superRefine(checkRetiredProcessKeys)
+    .superRefine(rejectExcludeRefPrefixesOutsideReflect);
 /** `processes.consolidate` — narrow per-process schema (WI-9.6). */
 export const ConsolidateProcessConfigSchema = z
     .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...CONSOLIDATE_PROCESS_FIELDS })
     .passthrough()
-    .superRefine(checkRetiredProcessKeys);
+    .superRefine(checkRetiredProcessKeys)
+    .superRefine(rejectExcludeRefPrefixesOutsideReflect);
 /** `processes.memoryInference` — narrow per-process schema (WI-9.6). */
 export const MemoryInferenceProcessConfigSchema = z
     .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...MEMORY_INFERENCE_PROCESS_FIELDS })

package/dist/core/improve-result.js

@@ -19,6 +19,7 @@ const COMMON_FIELDS = [
     "plan",
     "actions",
     "skippedProcesses",
+    "engineProbe",
     "distillSkipped",
     "validationFailures",
     "schemaRepairs",
@@ -27,6 +28,10 @@ const COMMON_FIELDS = [
     "lintSummary",
     "memoryIndexHealth",
     "coverageGaps",
+    // R10: no longer written (the write-only eval-cases path was removed),
+    // but kept in the allow-list so `decodeImproveResult` still reads
+    // improve-result envelopes a prior release wrote with this field —
+    // AGENTS.md "Reading persisted data".
     "evalCasesWritten",
     "deadUrls",
     "deadUrlCoverage",
@@ -35,6 +40,7 @@ const COMMON_FIELDS = [
     "graphExtraction",
     "memoryInferenceDurationMs",
     "graphExtractionDurationMs",
+    "ensureIndexDurationMs",
     "orphansPurged",
     "proposalsExpired",
     "reflectCooldownActions",
@@ -442,6 +448,7 @@ function validateCommon(value) {
     for (const field of [
         "actions",
         "skippedProcesses",
+        "engineProbe",
         "validationFailures",
         "schemaRepairs",
         "extract",
@@ -457,10 +464,12 @@ function validateCommon(value) {
     }
     for (const field of [
         "cyclesRun",
+        // R10: retired write, kept readable — see the COMMON_FIELDS comment above.
         "evalCasesWritten",
         "reflectsWithErrorContext",
         "memoryInferenceDurationMs",
         "graphExtractionDurationMs",
+        "ensureIndexDurationMs",
         "orphansPurged",
         "proposalsExpired",
         "reflectCooldownActions",

package/dist/core/paths.js

@@ -352,6 +352,13 @@ export function getDistillRejectedDir(stashDir) {
  * `$STATE/improve/eval-cases/<stash>/` — regression eval cases captured from
  * rejected distill/proposal output. Moved out of `$STASH/.akm/eval-cases/`
  * (itlackey/akm#890).
+ *
+ * R10: the writer (`src/commands/improve/eval-cases.ts`) was removed —
+ * nothing ever read the files it wrote, and a rejected proposal row now
+ * carries the same information (see `quality-gate.ts`'s
+ * `writeQualityRejection`). This resolver stays: `scripts/akm-migrate/migrate/
+ * writer-relocation.ts` still uses it to relocate pre-existing eval-case
+ * files an older release wrote to the legacy `$STASH/.akm/eval-cases/` path.
  */
 export function getEvalCasesDir(stashDir) {
     return stashScopedDir(path.join(getStateDir(), "improve", "eval-cases"), stashDir);

package/dist/core/write-source.js

@@ -1028,6 +1028,14 @@ export function assertAkmAssetWrite(source, allowedAdapters = ["akm"]) {
         return;
     throw new UsageError(`Bundle "${source.name}" uses adapter "${source.adapterId}", which does not support AKM asset writes.`, "INVALID_FLAG_VALUE");
 }
+/**
+ * The write-capable source kinds. Writes (and therefore scheduler state,
+ * which only ever binds to a writable source) are defined only for these
+ * two kinds; anything else throws `ConfigError`.
+ */
+export function isWriteCapableSourceKind(kind) {
+    return kind === "filesystem" || kind === "git";
+}
 /**
  * Reject any kind reaching the write/delete helpers other than the two
  * supported writable kinds. The config loader is the first line of defence
@@ -1035,7 +1043,7 @@ export function assertAkmAssetWrite(source, allowedAdapters = ["akm"]) {
  * bypass the loader still get a clear error.
  */
 function assertSupportedKind(source) {
-    if (source.kind === "filesystem" || source.kind === "git")
+    if (isWriteCapableSourceKind(source.kind))
         return;
     throw new ConfigError(`write-source: unsupported kind "${source.kind}" for source "${source.name}". ` +
         "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Set `kind: "filesystem"` (or `kind: "git"`) on the source, or add a parallel filesystem entry.');
@@ -1073,7 +1081,7 @@ function adaptConfiguredSource(runtime) {
     // reaching this point is a config-loader bug (assertWritableAllowedForKind
     // should have rejected it). Throw a ConfigError rather than silently
     // forwarding an unsupported kind.
-    if (runtime.type !== "filesystem" && runtime.type !== "git") {
+    if (!isWriteCapableSourceKind(runtime.type)) {
         throw new ConfigError(`write-source: source "${runtime.name}" has unsupported kind "${runtime.type}" for writes. ` +
             "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Use `kind: "filesystem"` or `kind: "git"` for writable sources.');
     }