akm-cli 0.9.0-beta.26 → 0.9.0-beta.28

package/dist/commands/improve/improve.js

@@ -683,6 +683,11 @@ export async function akmImprove(options = {}) {
     const ensureIndexFn = options.ensureIndexFn ?? ensureIndex;
     const reindexFn = options.reindexFn ?? akmIndex;
     const drainProposalsFn = options.drainProposalsFn ?? drainProposals;
+    // #616 multi-cycle test seams. Default to the real module-local fns.
+    const collectEligibleRefsImpl = options.collectEligibleRefsFn ?? collectEligibleRefs;
+    const runImprovePreparationStageImpl = options.runImprovePreparationStageFn ?? runImprovePreparationStage;
+    const runImproveLoopStageImpl = options.runImproveLoopStageFn ?? runImproveLoopStage;
+    const runImprovePostLoopStageImpl = options.runImprovePostLoopStageFn ?? runImprovePostLoopStage;
     // Resolve the improve profile for this run. Profile drives type filtering,
     // process gating, and default autoAccept/limit values.
     const _earlyConfig = options.config ?? loadConfig();
@@ -697,6 +702,9 @@ export async function akmImprove(options = {}) {
         // CLI --limit takes precedence over both.
         limit: options.limit ?? improveProfile?.processes?.reflect?.limit ?? improveProfile.limit,
     };
+    // #616 — bounded multi-cycle phasing. CLI/programmatic override wins over
+    // profile.maxCycles; default 1 => single pass (byte-identical to pre-#616).
+    const maxCycles = Math.max(1, Math.trunc(options.maxCycles ?? improveProfile.maxCycles ?? 1));
     let primaryStashDir;
     try {
         primaryStashDir = resolveSourceEntries(options.stashDir)[0]?.path;
@@ -741,70 +749,23 @@ export async function akmImprove(options = {}) {
     // Lock base directory — same `.akm/` under the primary stash dir.
     const lockBaseDir = primaryStashDir ? path.join(primaryStashDir, ".akm") : path.join(options.stashDir ?? ".", ".akm");
     const preEnsureCleanupWarnings = [];
-    let plannedRefs;
-    let memorySummary;
-    let profileFilteredRefs;
+    // #616: assigned by runIndexAndCollect() (closure) so TS cannot prove definite
+    // assignment — seed with empty values; the first runIndexAndCollect() call
+    // (cycle 1, in the first try) always overwrites them before any read.
+    let plannedRefs = [];
+    let memorySummary = { eligible: 0, derived: 0 };
+    let profileFilteredRefs = [];
     let memoryCleanupPlan;
     let guidance;
     let triageDrain;
-    try {
-        // #607: Per-process lock acquisition. Each process acquires only the lock(s)
-        // it needs. The dry-run branch produces plannedRefs/memorySummary WITHOUT any
-        // locks (decision: dry-run never mutates the queue).
-        if (!options.dryRun) {
-            // Backstop release on process.exit() (signal handler / budget watchdog),
-            // which skips the finally below. Removed in that finally on the normal path.
-            const releaseAllOnExit = () => {
-                for (const p of heldProcessLocks) {
-                    releaseLockIfOwned(p, process.pid);
-                }
-            };
-            process.on("exit", releaseAllOnExit);
-            // #607 triage pre-pass: acquire triage.lock, drain the standing pending
-            // backlog BEFORE ensureIndex so improve generates fresh proposals against
-            // a cleared queue (no `duplicate_pending` collisions) and ensureIndex
-            // absorbs triage's promotions for free. Release immediately after —
-            // triage.lock is not needed again until the next improve run.
-            if (primaryStashDir && resolveProcessEnabled("triage", improveProfile)) {
-                if (scope.mode === "ref") {
-                    warn("[improve] triage pre-pass skipped (single-ref scope never drains the whole queue)");
-                }
-                else {
-                    const triageLPath = processLockPath(lockBaseDir, "triage");
-                    const triageResult = tryAcquireProcessLock(triageLPath, PROCESS_LOCK_DEFS.triage.staleAfterMs, options.skipIfLocked, "triage");
-                    if (triageResult === "skipped") {
-                        triageDrain = undefined;
-                    }
-                    else {
-                        try {
-                            const triageConfig = improveProfile.processes?.triage;
-                            const policy = resolveDrainPolicy(triageConfig?.policy);
-                            const applyMode = triageConfig?.applyMode ?? "queue";
-                            const maxAccepts = triageConfig?.maxAcceptsPerRun ?? 25;
-                            const judgment = triageConfig?.judgment
-                                ? resolveTriageJudgmentRunner(triageConfig.judgment, _earlyConfig)
-                                : null;
-                            triageDrain = await drainProposalsFn({
-                                stashDir: primaryStashDir,
-                                policy,
-                                applyMode,
-                                maxAccepts,
-                                dryRun: false,
-                                excludeIds: new Set(),
-                                ...(triageConfig?.maxDiffLines !== undefined ? { maxDiffLines: triageConfig.maxDiffLines } : {}),
-                                judgment,
-                            });
-                        }
-                        catch (err) {
-                            warn(`[improve] triage pre-pass failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
-                        }
-                        finally {
-                            releaseProcessLock(triageLPath);
-                        }
-                    }
-                }
-            }
-        }
+    // #616 — ensureIndex + collectEligibleRefs + memory-cleanup recompute, lifted
+    // into a helper so the SAME sequence runs once for cycle 1 (below, in the
+    // first try) and is re-run at the top of each subsequent multi-cycle cycle.
+    // Re-running ensureIndex between cycles makes cycle N's gate-promoted
+    // proposals visible to cycle N+1's collectEligibleRefs. Mutates the
+    // outer-scope plannedRefs/memorySummary/profileFilteredRefs/memoryCleanupPlan/
+    // guidance so for maxCycles:1 the body is byte-identical to pre-#616.
+    const runIndexAndCollect = async () => {
         // #339 fix: ensureIndex MUST run BEFORE collectEligibleRefs. The eligible-ref
         // query reads the `entries` table; if a DB version upgrade just dropped that
         // table (or the index is otherwise empty), the prior run order silently
@@ -862,7 +823,7 @@ export async function akmImprove(options = {}) {
                 }
             }
         }
-        ({ plannedRefs, memorySummary, profileFilteredRefs } = await collectEligibleRefs(scope, options.stashDir, improveProfile));
+        ({ plannedRefs, memorySummary, profileFilteredRefs } = await collectEligibleRefsImpl(scope, options.stashDir, improveProfile));
         const cleanupParentRef = memoryCleanupParentRef(scope, options.stashDir);
         // M-1 (#367): Run contradiction-detection BEFORE analyzeMemoryCleanup so
         // the SCC resolver in resolveFamilyContradictions has edges to work on.
@@ -884,6 +845,69 @@ export async function akmImprove(options = {}) {
             memorySummary.eligible > 0
                 ? "Improve folds memory cleanup into the same proposal queue: speculative promotions still go through reflect/distill proposals, while high-confidence redundant derived memories are moved into a recoverable cleanup archive instead of being left active in the stash."
                 : undefined;
+    };
+    try {
+        // #607: Per-process lock acquisition. Each process acquires only the lock(s)
+        // it needs. The dry-run branch produces plannedRefs/memorySummary WITHOUT any
+        // locks (decision: dry-run never mutates the queue).
+        if (!options.dryRun) {
+            // Backstop release on process.exit() (signal handler / budget watchdog),
+            // which skips the finally below. Removed in that finally on the normal path.
+            const releaseAllOnExit = () => {
+                for (const p of heldProcessLocks) {
+                    releaseLockIfOwned(p, process.pid);
+                }
+            };
+            process.on("exit", releaseAllOnExit);
+            // #607 triage pre-pass: acquire triage.lock, drain the standing pending
+            // backlog BEFORE ensureIndex so improve generates fresh proposals against
+            // a cleared queue (no `duplicate_pending` collisions) and ensureIndex
+            // absorbs triage's promotions for free. Release immediately after —
+            // triage.lock is not needed again until the next improve run.
+            if (primaryStashDir && resolveProcessEnabled("triage", improveProfile)) {
+                if (scope.mode === "ref") {
+                    warn("[improve] triage pre-pass skipped (single-ref scope never drains the whole queue)");
+                }
+                else {
+                    const triageLPath = processLockPath(lockBaseDir, "triage");
+                    const triageResult = tryAcquireProcessLock(triageLPath, PROCESS_LOCK_DEFS.triage.staleAfterMs, options.skipIfLocked, "triage");
+                    if (triageResult === "skipped") {
+                        triageDrain = undefined;
+                    }
+                    else {
+                        try {
+                            const triageConfig = improveProfile.processes?.triage;
+                            const policy = resolveDrainPolicy(triageConfig?.policy);
+                            const applyMode = triageConfig?.applyMode ?? "queue";
+                            const maxAccepts = triageConfig?.maxAcceptsPerRun ?? 25;
+                            const judgment = triageConfig?.judgment
+                                ? resolveTriageJudgmentRunner(triageConfig.judgment, _earlyConfig)
+                                : null;
+                            triageDrain = await drainProposalsFn({
+                                stashDir: primaryStashDir,
+                                policy,
+                                applyMode,
+                                maxAccepts,
+                                dryRun: false,
+                                excludeIds: new Set(),
+                                ...(triageConfig?.maxDiffLines !== undefined ? { maxDiffLines: triageConfig.maxDiffLines } : {}),
+                                judgment,
+                            });
+                        }
+                        catch (err) {
+                            warn(`[improve] triage pre-pass failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+                        }
+                        finally {
+                            releaseProcessLock(triageLPath);
+                        }
+                    }
+                }
+            }
+        }
+        // #339 fix: ensureIndex MUST run BEFORE collectEligibleRefs (now inside the
+        // helper). Cycle 1 runs it here; subsequent multi-cycle cycles re-run it via
+        // the same helper at the top of each cycle below.
+        await runIndexAndCollect();
         if (options.dryRun) {
             const result = {
                 schemaVersion: 1,
@@ -981,89 +1005,194 @@ export async function akmImprove(options = {}) {
                 },
             }, eventsCtx);
         }
-        // #607: acquire consolidate.lock for the preparation stage (consolidate,
-        // ensureIndex, extract all write index.db). Released immediately after.
-        const consolidateLPath = processLockPath(lockBaseDir, "consolidate");
-        const consolidatePrepAcquired = tryAcquireProcessLock(consolidateLPath, PROCESS_LOCK_DEFS.consolidate.staleAfterMs, options.skipIfLocked, "consolidate") === "acquired";
-        const preparation = await runImprovePreparationStage({
-            scope,
-            options,
-            plannedRefs,
-            memoryCleanupPlan,
-            primaryStashDir,
-            memorySummary,
-            reindexFn,
-            startMs,
-            budgetMs,
-            eventsCtx,
-            initialCleanupWarnings: preEnsureCleanupWarnings,
-            improveProfile,
-            budgetSignal: budgetAbortController.signal,
-        });
-        if (consolidatePrepAcquired)
-            releaseProcessLock(consolidateLPath);
-        // D6: pre-load all proposal_rejected events from the last 30 days once,
-        // so the per-asset loop can use a Map lookup instead of N DB round trips.
-        const REJECTED_PROPOSAL_WINDOW_MS = daysToMs(30);
-        const rejectedProposalSince = new Date(Date.now() - REJECTED_PROPOSAL_WINDOW_MS).toISOString();
-        const allRejectedProposalEvents = readEvents({ type: "proposal_rejected", since: rejectedProposalSince }).events;
-        const rejectedProposalsByRef = new Map();
-        for (const e of allRejectedProposalEvents) {
-            if (e.ref && (!rejectedProposalsByRef.has(e.ref) || e.ts > (rejectedProposalsByRef.get(e.ref)?.ts ?? ""))) {
-                rejectedProposalsByRef.set(e.ref, e);
+        // #616 — bounded multi-cycle phasing. The prep->loop->post-loop sequence is
+        // wrapped in an N-cycle loop. Each cycle re-runs ensureIndex +
+        // collectEligibleRefs (via runIndexAndCollect) so gate-accepted output of
+        // cycle N becomes selectable input to cycle N+1. The per-stage process locks
+        // (consolidate / reflect-distill) are acquired+released INSIDE each cycle,
+        // exactly as the single-pass path did. For maxCycles:1 the loop runs once and
+        // every accumulator below collapses to the single-cycle value (sum-of-one,
+        // concat-of-one, last==only) => BYTE-IDENTICAL to pre-#616.
+        //
+        // Accumulators (see CONSTRAINTS / aggregation plan in #616): SUM the count
+        // fields and durations; CONCAT the array fields; LAST-WINS for point-in-time
+        // objects (the final cycle's value reflects the converged state).
+        let cyclesRun = 0;
+        // Last-wins point-in-time values (assigned every cycle; the final cycle wins).
+        let preparation;
+        let memoryRefsForInference = new Set();
+        let consolidation;
+        let memoryInference;
+        let graphExtraction;
+        let stalenessDetection;
+        let recombination;
+        let proceduralCompilation;
+        // Summed counters/durations.
+        let prepGateCount = 0;
+        let prepGateFailedCount = 0;
+        let reflectsWithErrorContext = 0;
+        let loopGateCount = 0;
+        let loopGateFailedCount = 0;
+        let postLoopGateCount = 0;
+        let postLoopGateFailedCount = 0;
+        let memoryInferenceDurationMs = 0;
+        let graphExtractionDurationMs = 0;
+        let orphansPurged;
+        let proposalsExpired;
+        // Concatenated arrays.
+        const allWarnings = [];
+        let deadUrls;
+        const finalActions = [];
+        for (let cycleIndex = 0; cycleIndex < maxCycles; cycleIndex++) {
+            // #616 budget gate: never start a NEW cycle once the run's wall-clock
+            // budget is exhausted (or the run was aborted). Cycle 0 ALWAYS runs so
+            // maxCycles:1 is byte-identical regardless of budget.
+            if (cycleIndex > 0) {
+                const remaining = budgetAbortController.signal.remainingBudgetMs;
+                if (budgetAbortController.signal.aborted || (remaining !== undefined && remaining <= 0)) {
+                    break;
+                }
+            }
+            // Re-run ensureIndex + collectEligibleRefs + memory-cleanup recompute for
+            // cycles 2+ (cycle 1 already ran them in the first try above). This makes
+            // cycle N's gate-promoted proposals visible to this cycle's ref selection.
+            if (cycleIndex > 0) {
+                await runIndexAndCollect();
+                // Re-emit the profile-filtered audit summary for this cycle's selection.
+                if (profileFilteredRefs.length > 0) {
+                    appendEvent({
+                        eventType: "improve_skipped",
+                        ref: undefined,
+                        metadata: { reason: "profile_filtered_all_passes", count: profileFilteredRefs.length },
+                    }, eventsCtx);
+                }
+            }
+            // #607: acquire consolidate.lock for the preparation stage (consolidate,
+            // ensureIndex, extract all write index.db). Released immediately after.
+            const consolidateLPath = processLockPath(lockBaseDir, "consolidate");
+            const consolidatePrepAcquired = tryAcquireProcessLock(consolidateLPath, PROCESS_LOCK_DEFS.consolidate.staleAfterMs, options.skipIfLocked, "consolidate") === "acquired";
+            preparation = await runImprovePreparationStageImpl({
+                scope,
+                options,
+                plannedRefs,
+                memoryCleanupPlan,
+                primaryStashDir,
+                memorySummary,
+                reindexFn,
+                startMs,
+                budgetMs,
+                eventsCtx,
+                initialCleanupWarnings: preEnsureCleanupWarnings,
+                improveProfile,
+                budgetSignal: budgetAbortController.signal,
+            });
+            if (consolidatePrepAcquired)
+                releaseProcessLock(consolidateLPath);
+            prepGateCount += preparation.gateAutoAcceptedCount;
+            prepGateFailedCount += preparation.gateAutoAcceptFailedCount;
+            // D6: pre-load all proposal_rejected events from the last 30 days once,
+            // so the per-asset loop can use a Map lookup instead of N DB round trips.
+            const REJECTED_PROPOSAL_WINDOW_MS = daysToMs(30);
+            const rejectedProposalSince = new Date(Date.now() - REJECTED_PROPOSAL_WINDOW_MS).toISOString();
+            const allRejectedProposalEvents = readEvents({ type: "proposal_rejected", since: rejectedProposalSince }).events;
+            const rejectedProposalsByRef = new Map();
+            for (const e of allRejectedProposalEvents) {
+                if (e.ref && (!rejectedProposalsByRef.has(e.ref) || e.ts > (rejectedProposalsByRef.get(e.ref)?.ts ?? ""))) {
+                    rejectedProposalsByRef.set(e.ref, e);
+                }
+            }
+            // #607: acquire reflect-distill.lock for the loop stage (reflect + distill
+            // both write proposals to state.db). Released immediately after.
+            const reflectDistillLPath = processLockPath(lockBaseDir, "reflectDistill");
+            const reflectDistillAcquired = tryAcquireProcessLock(reflectDistillLPath, PROCESS_LOCK_DEFS.reflectDistill.staleAfterMs, options.skipIfLocked, "reflect-distill") === "acquired";
+            const loopResult = await runImproveLoopStageImpl({
+                scope,
+                options,
+                primaryStashDir,
+                reflectFn,
+                distillFn,
+                loopRefs: preparation.loopRefs,
+                actions: preparation.actions,
+                signalBearingSet: preparation.signalBearingSet,
+                distillCooledRefs: preparation.distillCooledRefs,
+                distillOnlyRefs: preparation.distillOnlyRefs,
+                recentErrors: preparation.recentErrors,
+                rejectedProposalsByRef,
+                utilityMap: preparation.utilityMap,
+                startMs,
+                budgetMs,
+                eventsCtx,
+                improveProfile,
+                budgetSignal: budgetAbortController.signal,
+            });
+            if (reflectDistillAcquired)
+                releaseProcessLock(reflectDistillLPath);
+            const loopGateCountThisCycle = loopResult.gateAutoAcceptedCount;
+            reflectsWithErrorContext += loopResult.reflectsWithErrorContext;
+            loopGateCount += loopResult.gateAutoAcceptedCount;
+            loopGateFailedCount += loopResult.gateAutoAcceptFailedCount;
+            memoryRefsForInference = loopResult.memoryRefsForInference;
+            // #551: consolidation now runs in the preparation stage (before extract);
+            // its result and run-flag are read from `preparation`, not the post-loop.
+            consolidation = preparation.consolidation;
+            // #607: acquire consolidate.lock for the post-loop stage (memoryInference +
+            // graphExtraction both write index.db). Released immediately after.
+            const consolidatePostLPath = processLockPath(lockBaseDir, "consolidate");
+            const consolidatePostAcquired = tryAcquireProcessLock(consolidatePostLPath, PROCESS_LOCK_DEFS.consolidate.staleAfterMs, options.skipIfLocked, "consolidate") === "acquired";
+            const postLoopResult = await runImprovePostLoopStageImpl({
+                scope,
+                options,
+                primaryStashDir,
+                actionableRefs: preparation.actionableRefs,
+                appliedCleanup: preparation.appliedCleanup,
+                cleanupWarnings: preparation.cleanupWarnings,
+                memoryRefsForInference,
+                reindexFn,
+                eventsCtx,
+                budgetSignal: budgetAbortController.signal,
+                improveProfile,
+                consolidationRan: preparation.consolidationRan,
+            });
+            if (consolidatePostAcquired)
+                releaseProcessLock(consolidatePostLPath);
+            const postLoopGateCountThisCycle = postLoopResult.gateAutoAcceptedCount;
+            // Last-wins point-in-time objects.
+            memoryInference = postLoopResult.memoryInference;
+            graphExtraction = postLoopResult.graphExtraction;
+            stalenessDetection = postLoopResult.stalenessDetection;
+            recombination = postLoopResult.recombination;
+            proceduralCompilation = postLoopResult.proceduralCompilation;
+            // Summed counters/durations.
+            postLoopGateCount += postLoopResult.gateAutoAcceptedCount;
+            postLoopGateFailedCount += postLoopResult.gateAutoAcceptFailedCount;
+            memoryInferenceDurationMs += postLoopResult.memoryInferenceDurationMs;
+            graphExtractionDurationMs += postLoopResult.graphExtractionDurationMs;
+            if (postLoopResult.orphansPurged !== undefined) {
+                orphansPurged = (orphansPurged ?? 0) + postLoopResult.orphansPurged;
+            }
+            if (postLoopResult.proposalsExpired !== undefined) {
+                proposalsExpired = (proposalsExpired ?? 0) + postLoopResult.proposalsExpired;
             }
+            // Concatenated arrays.
+            allWarnings.push(...postLoopResult.allWarnings);
+            if (postLoopResult.deadUrls !== undefined) {
+                deadUrls = [...(deadUrls ?? []), ...postLoopResult.deadUrls];
+            }
+            const maintenanceActions = postLoopResult.maintenanceActions;
+            if (maintenanceActions && maintenanceActions.length > 0) {
+                finalActions.push(...preparation.actions, ...maintenanceActions);
+            }
+            else {
+                finalActions.push(...preparation.actions);
+            }
+            cyclesRun++;
+            // #616 fixed-point stop: a cycle that produced ZERO gate-accepted proposals
+            // (summed across prep + loop + post-loop) would feed cycle N+1 an identical
+            // ref set, so end the loop here rather than spin a pointless next cycle.
+            const gateAcceptedThisCycle = preparation.gateAutoAcceptedCount + loopGateCountThisCycle + postLoopGateCountThisCycle;
+            if (gateAcceptedThisCycle === 0)
+                break;
         }
-        // #607: acquire reflect-distill.lock for the loop stage (reflect + distill
-        // both write proposals to state.db). Released immediately after.
-        const reflectDistillLPath = processLockPath(lockBaseDir, "reflectDistill");
-        const reflectDistillAcquired = tryAcquireProcessLock(reflectDistillLPath, PROCESS_LOCK_DEFS.reflectDistill.staleAfterMs, options.skipIfLocked, "reflect-distill") === "acquired";
-        const { reflectsWithErrorContext, memoryRefsForInference, gateAutoAcceptedCount: loopGateCount, gateAutoAcceptFailedCount: loopGateFailedCount, } = await runImproveLoopStage({
-            scope,
-            options,
-            primaryStashDir,
-            reflectFn,
-            distillFn,
-            loopRefs: preparation.loopRefs,
-            actions: preparation.actions,
-            signalBearingSet: preparation.signalBearingSet,
-            distillCooledRefs: preparation.distillCooledRefs,
-            distillOnlyRefs: preparation.distillOnlyRefs,
-            recentErrors: preparation.recentErrors,
-            rejectedProposalsByRef,
-            utilityMap: preparation.utilityMap,
-            startMs,
-            budgetMs,
-            eventsCtx,
-            improveProfile,
-        });
-        if (reflectDistillAcquired)
-            releaseProcessLock(reflectDistillLPath);
-        // #551: consolidation now runs in the preparation stage (before extract);
-        // its result and run-flag are read from `preparation`, not the post-loop.
-        const consolidation = preparation.consolidation;
-        // #607: acquire consolidate.lock for the post-loop stage (memoryInference +
-        // graphExtraction both write index.db). Released immediately after.
-        const consolidatePostLPath = processLockPath(lockBaseDir, "consolidate");
-        const consolidatePostAcquired = tryAcquireProcessLock(consolidatePostLPath, PROCESS_LOCK_DEFS.consolidate.staleAfterMs, options.skipIfLocked, "consolidate") === "acquired";
-        const { allWarnings, deadUrls, memoryInference, graphExtraction, stalenessDetection, maintenanceActions, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, gateAutoAcceptedCount: postLoopGateCount, gateAutoAcceptFailedCount: postLoopGateFailedCount, recombination, proceduralCompilation, } = await runImprovePostLoopStage({
-            scope,
-            options,
-            primaryStashDir,
-            actionableRefs: preparation.actionableRefs,
-            appliedCleanup: preparation.appliedCleanup,
-            cleanupWarnings: preparation.cleanupWarnings,
-            memoryRefsForInference,
-            reindexFn,
-            eventsCtx,
-            budgetSignal: budgetAbortController.signal,
-            improveProfile,
-            consolidationRan: preparation.consolidationRan,
-        });
-        if (consolidatePostAcquired)
-            releaseProcessLock(consolidatePostLPath);
-        const finalActions = maintenanceActions && maintenanceActions.length > 0
-            ? [...preparation.actions, ...maintenanceActions]
-            : preparation.actions;
         const result = {
             schemaVersion: 1,
             ok: true,
@@ -1130,11 +1259,11 @@ export async function akmImprove(options = {}) {
             reflectSkippedActions: finalActions.filter((a) => a.mode === "reflect-skipped").length,
             reflectGuardRejectedActions: finalActions.filter((a) => a.mode === "reflect-guard-rejected").length,
             ...(() => {
-                const t = preparation.gateAutoAcceptedCount + loopGateCount + postLoopGateCount;
+                const t = prepGateCount + loopGateCount + postLoopGateCount;
                 return t > 0 ? { gateAutoAcceptedCount: t } : {};
             })(),
             ...(() => {
-                const f = preparation.gateAutoAcceptFailedCount + loopGateFailedCount + postLoopGateFailedCount;
+                const f = prepGateFailedCount + loopGateFailedCount + postLoopGateFailedCount;
                 return f > 0 ? { gateAutoAcceptFailedCount: f } : {};
             })(),
             ...(triageDrain
@@ -1148,6 +1277,9 @@ export async function akmImprove(options = {}) {
                 }
                 : {}),
             ...(preparation.proactiveMaintenance ? { proactiveMaintenance: preparation.proactiveMaintenance } : {}),
+            // #616 — report cycles run only when >1 so the default single-pass
+            // serialized envelope stays byte-identical to pre-#616 (AC1).
+            ...(cyclesRun > 1 ? { cyclesRun } : {}),
             ...(options.runId !== undefined ? { runId: options.runId } : {}),
         };
         if (!result.dryRun)
@@ -3900,6 +4032,9 @@ export async function runImproveMaintenancePasses(args) {
             const graphEnabled = isProcessEnabled("index", "graph_extraction", config);
             const graphExtractionDisabledByProfile = improveProfile?.processes?.graphExtraction?.enabled === false;
             const graphExtractionFullScan = improveProfile?.processes?.graphExtraction?.fullScan === true;
+            // #624 P2: optional incremental high-signal-first cap. Unset = process all
+            // eligible (byte-identical to today; no ranking/slice).
+            const graphExtractionTopN = improveProfile?.processes?.graphExtraction?.topN;
             // Build the set of refs actually touched this run.
             const touchedRefs = new Set();
             for (const r of args.actionableRefs)
@@ -3961,7 +4096,7 @@ export async function runImproveMaintenancePasses(args) {
                         db,
                         reEnrich: false,
                         onProgress: progressHandler,
-                        options: { candidatePaths },
+                        options: { candidatePaths, ...(graphExtractionTopN != null ? { topN: graphExtractionTopN } : {}) },
                     }));
                     graphExtractionDurationMs = Date.now() - extractionStart;
                     actions.push({ ref: "graph:_artifact", mode: "graph-extraction", result: graphExtraction });

package/dist/commands/lint/fact-linter.js

@@ -0,0 +1,39 @@
+// 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/.
+import { BaseLinter } from "./base-linter.js";
+/** Recommended `category` values for facts (see docs/design/fact-asset-type.md). */
+const KNOWN_CATEGORIES = new Set(["personal", "team", "project", "convention", "meta"]);
+/**
+ * Linter for `facts/` assets.
+ *
+ * Extra check beyond base:
+ *   - `missing-category`: a fact without a non-empty `category` frontmatter
+ *     key. Category scopes the fact (personal/team/project/convention/meta)
+ *     and drives how it is surfaced/injected, so it is expected. Reported as a
+ *     non-fixable warning — we cannot infer the right scope automatically.
+ */
+export class FactLinter extends BaseLinter {
+    types = ["facts"];
+    lint(ctx) {
+        const issues = this.runBaseChecks(ctx);
+        const category = typeof ctx.data.category === "string" ? ctx.data.category.trim() : "";
+        if (!category) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "missing-category",
+                detail: "fact is missing a `category` (personal|team|project|convention|meta)",
+                fixed: false,
+            });
+        }
+        else if (!KNOWN_CATEGORIES.has(category)) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "missing-category",
+                detail: `unrecognized category "${category}" (expected one of: ${[...KNOWN_CATEGORIES].join(", ")})`,
+                fixed: false,
+            });
+        }
+        return issues;
+    }
+}

package/dist/commands/lint/index.js

@@ -20,6 +20,7 @@ const STASH_SUBDIRS = [
     "lessons",
     "tasks",
     "knowledge",
+    "facts",
 ];
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function collectYamlFiles(dir) {

package/dist/commands/lint/registry.js

@@ -4,6 +4,7 @@
 import { AgentLinter } from "./agent-linter.js";
 import { CommandLinter } from "./command-linter.js";
 import { DefaultLinter } from "./default-linter.js";
+import { FactLinter } from "./fact-linter.js";
 import { KnowledgeLinter } from "./knowledge-linter.js";
 import { MemoryLinter } from "./memory-linter.js";
 import { SkillLinter } from "./skill-linter.js";
@@ -18,6 +19,7 @@ const LINTERS = [
     new KnowledgeLinter(),
     new SkillLinter(),
     new TaskLinter(),
+    new FactLinter(),
 ];
 // Single shared DefaultLinter instance — used both as the explicit "lessons"
 // handler and as the fallback for any unrecognised asset type.

package/dist/commands/read/curate.js

@@ -13,12 +13,18 @@
  * helpers (`curateSearchResults`, `deriveCurateFallbackQueries`,
  * `mergeCurateSearchResponses`) by importing them directly.
  */
+import fs from "node:fs";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
+import { closeDatabase, computeBodyHash, openExistingDatabase } from "../../indexer/db/db.js";
+import { enqueueGraphExtraction, hasGraphData } from "../../indexer/db/graph-db.js";
+import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { truncateDescription } from "../../output/shapes.js";
+import { withIndexDb } from "../../storage/repositories/index-db.js";
 import { akmSearch, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
 const CURATE_FALLBACK_FILTER_WORDS = new Set([
@@ -145,6 +151,11 @@ async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs) {
     catch {
         shown = undefined;
     }
+    // #624-P3: when lazy graph extraction is opted in, enqueue an ungraphed
+    // asset for a later pass to extract. Fire-and-forget, non-blocking, NO inline
+    // extraction and NO LLM call here. Default-off (flag unset) = byte-identical.
+    if (shown?.path)
+        maybeEnqueueLazyGraph(shown.path);
     const description = shown?.description ?? hit.description;
     const preview = buildCuratedPreview(shown, hit);
     const mergedSupportRefs = mergeCurateSupportRefs(supportRefs, shown?.related?.hits, selectedRefs, hit.ref);
@@ -164,6 +175,44 @@ async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs) {
         ...(hit.score !== undefined ? { score: hit.score } : {}),
     };
 }
+/**
+ * #624-P3 — enqueue an ungraphed asset for lazy graph extraction when the
+ * `index.graph.lazyGraphExtraction` flag is on. Pure side-effect, fully
+ * best-effort: any failure (config, fs, db) is swallowed so curate never fails
+ * on it. NO LLM call and NO inline extraction — only a cheap queue insert.
+ * Default-off (flag unset) returns immediately = byte-identical behavior.
+ */
+function maybeEnqueueLazyGraph(assetPath) {
+    try {
+        const config = loadConfig();
+        if (getIndexPassConfig(config.index, "graph")?.lazyGraphExtraction !== true)
+            return;
+        const sources = resolveSourceEntries();
+        const source = findSourceForPath(assetPath, sources);
+        const stashRoot = source?.path;
+        if (!stashRoot)
+            return;
+        let raw;
+        try {
+            raw = fs.readFileSync(assetPath, "utf8");
+        }
+        catch {
+            return;
+        }
+        const body = parseFrontmatter(raw).content.trim();
+        if (!body)
+            return;
+        const bodyHash = computeBodyHash(body);
+        withIndexDb((db) => {
+            if (!hasGraphData(db, stashRoot, assetPath)) {
+                enqueueGraphExtraction(db, stashRoot, assetPath, bodyHash, 0);
+            }
+        });
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+    }
+}
 function buildCuratedRegistryItem(query, hit) {
     return {
         source: "registry",