akm-cli 0.9.16-alpha.2 → 0.9.17-alpha.1

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/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/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/indexer/ensure-index.js

@@ -21,11 +21,13 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { hashContent } from "../core/adapter/adapters/shared.js";
 import { placementSpecList } from "../core/asset/asset-placement.js";
 import { classifyPathAccess } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
+import { warnVerbose } from "../core/warn.js";
 import { assertIndexPathReadable, closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
-import { getEntryCount, getIndexedFilePaths } from "../storage/repositories/index-entries-repository.js";
+import { getEntryCount, getIndexedFileHashes, getIndexedFilePaths, } from "../storage/repositories/index-entries-repository.js";
 import { isCanonicalIndexGeneration } from "../storage/repositories/index-entry-schema.js";
 import { getMeta } from "../storage/repositories/index-meta-repository.js";
 import { warnOnBundleRenameDrift } from "./bundle-identity-guard.js";
@@ -77,11 +79,20 @@ function getIndexableFiles(root, spec) {
  *      millisecond-truncated), so the mtime test alone silently misses
  *      additions made within ~a millisecond of the previous build.
  *
+ * A file whose mtime is newer than `builtAt` is NOT automatically stale
+ * (R6): `indexWrittenAssets` upserts a fresh `content_hash` without bumping
+ * `builtAt`, so a file `ensureIndex` itself just incrementally re-indexed
+ * (for example a proposal triage just promoted into `knowledge/`) would
+ * otherwise keep tripping this check on every subsequent call, forcing the
+ * full rescan the write-path fast path exists to avoid. Only files newer
+ * than `builtAt` are hashed here, so this stays cheap — the common case is
+ * zero or a handful of such files.
+ *
  * `getIndexableFiles` applies each asset type's own relevance filter, so
  * non-indexed companion files (e.g. `package.json` next to a knowledge doc) are
  * never considered and do not produce false "new file" positives.
  */
-function hasNewerIndexableFiles(stashDir, builtAt, indexedPaths) {
+function hasNewerIndexableFiles(stashDir, builtAt, indexedPaths, indexedHashes) {
     const builtAtMs = builtAt ? new Date(builtAt).getTime() : Number.NaN;
     const builtAtUsable = Number.isFinite(builtAtMs);
     for (const spec of placementSpecList()) {
@@ -92,13 +103,31 @@ function hasNewerIndexableFiles(stashDir, builtAt, indexedPaths) {
                 return true;
             if (!builtAtUsable)
                 return true;
+            let mtimeMs;
             try {
-                if (fs.statSync(file).mtimeMs > builtAtMs)
-                    return true;
+                mtimeMs = fs.statSync(file).mtimeMs;
+            }
+            catch {
+                return true;
+            }
+            if (mtimeMs <= builtAtMs)
+                continue;
+            // Newer than the last full build — only stale if its current content
+            // actually differs from what is indexed. No stored hash means the row
+            // predates content-hash tracking (or a hash-less enrichment pass), so
+            // fall back to the conservative mtime-stale answer.
+            const indexedHash = indexedHashes.get(file);
+            if (indexedHash === undefined)
+                return true;
+            let currentHash;
+            try {
+                currentHash = hashContent(fs.readFileSync(file, "utf8"));
             }
             catch {
                 return true;
             }
+            if (currentHash !== indexedHash)
+                return true;
         }
     }
     return false;
@@ -125,7 +154,7 @@ export function isIndexStale(stashDir) {
         if (entryCount === 0)
             return true;
         const builtAt = getMeta(db, "builtAt");
-        if (hasNewerIndexableFiles(stashDir, builtAt, getIndexedFilePaths(db)))
+        if (hasNewerIndexableFiles(stashDir, builtAt, getIndexedFilePaths(db), getIndexedFileHashes(db)))
             return true;
         const storedStashDir = getMeta(db, "stashDir");
         if (storedStashDir !== stashDir) {
@@ -193,12 +222,24 @@ function indexCanServeStash(stashDir) {
 }
 async function runInlineReindex(stashDir, options = {}) {
     const { akmIndex } = await import("./indexer.js");
-    await akmIndex({
+    const startedMs = Date.now();
+    const response = await akmIndex({
         stashDir,
         implicit: true,
         ...(options.signal ? { signal: options.signal } : {}),
         ...(options.hydrateSources === false ? { hydrateSources: false } : {}),
     });
+    // R6: the implicit reindex's cost was previously discarded entirely
+    // (`await akmIndex(...)` and nothing else), making a 27-minute blocking
+    // rebuild invisible to both the operator and the improve result. Fall back
+    // to a wall-clock measurement when the response carries no `timing` block.
+    const durationMs = response.timing?.totalMs ?? Date.now() - startedMs;
+    const timing = response.timing;
+    warnVerbose(`[ensure-index] implicit reindex completed in ${durationMs}ms` +
+        (timing
+            ? ` (walk=${timing.walkMs}ms llm=${timing.llmMs}ms embed=${timing.embedMs}ms finalize=${timing.finalizeMs}ms)`
+            : ""));
+    options.onReindexTiming?.({ durationMs, timing });
     return true;
 }
 /**
@@ -226,7 +267,10 @@ export async function ensureIndex(stashDir, options = {}) {
         // materialization point — hydrate cache-backed sources as usual.
         if (!isIndexStale(stashDir))
             return false;
-        return runInlineReindex(stashDir, { ...(options.signal ? { signal: options.signal } : {}) });
+        return runInlineReindex(stashDir, {
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.onReindexTiming ? { onReindexTiming: options.onReindexTiming } : {}),
+        });
     }
     // Background = the READ path (`show` auto-index): query time must never clone/
     // pull/fetch (spec §14.3 / D11). Build from already-materialized content only;
@@ -236,5 +280,6 @@ export async function ensureIndex(stashDir, options = {}) {
     return runInlineReindex(stashDir, {
         ...(options.signal ? { signal: options.signal } : {}),
         hydrateSources: false,
+        ...(options.onReindexTiming ? { onReindexTiming: options.onReindexTiming } : {}),
     });
 }