akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/commands/feedback-cli.js

@@ -2,8 +2,7 @@
 // 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 fs from "node:fs";
-import { defineCommand } from "citty";
-import { output, parseAllFlagValues, runWithJsonErrors } from "../cli/shared.js";
+import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.js";
 import { parseAssetRef } from "../core/asset/asset-ref.js";
 import { assembleAsset } from "../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../core/asset/frontmatter.js";
@@ -11,11 +10,9 @@ import { writeFileAtomic } from "../core/common.js";
 import { FEEDBACK_FAILURE_MODES, loadConfig } from "../core/config/config.js";
 import { UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
+import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
 import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, getEntryFilePathById, openExistingDatabase, } from "../indexer/db/db.js";
-import { ensureIndex } from "../indexer/ensure-index.js";
-import { withIndexWriterLease } from "../indexer/index-writer-lock.js";
-import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { countFeedbackSignals, insertUsageEvent } from "../indexer/usage/usage-events.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
 const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
@@ -110,7 +107,7 @@ function appendLessonStrength(type, name, feedbackRef) {
     return { strength: strengthList.length };
 }
 // ── Command definition ────────────────────────────────────────────────────────
-export const feedbackCommand = defineCommand({
+export const feedbackCommand = defineJsonCommand({
     meta: {
         name: "feedback",
         description: "Record positive or negative feedback for any indexed stash asset.\n\n" +
@@ -154,167 +151,171 @@ export const feedbackCommand = defineCommand({
                 "`lessonStrength[]` frontmatter array (dedup, idempotent). Ignored on non-lesson targets.",
         },
     },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            const ref = (args.ref ?? "").trim();
-            if (!ref) {
-                throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skill:deploy` and either --positive or --negative.");
+    async run({ args }) {
+        const ref = (args.ref ?? "").trim();
+        if (!ref) {
+            throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skill:deploy` and either --positive or --negative.");
+        }
+        parseAssetRef(ref);
+        if (args.positive && args.negative) {
+            throw new UsageError("Specify either --positive or --negative, not both.");
+        }
+        if (!args.positive && !args.negative) {
+            throw new UsageError("Specify --positive or --negative.");
+        }
+        const signal = args.positive ? "positive" : "negative";
+        const reason = args.reason;
+        // F-3 / #384: Validate --failure-mode against the curated enum.
+        const failureMode = args["failure-mode"]?.trim() || undefined;
+        if (failureMode) {
+            if (args.positive) {
+                throw new UsageError("--failure-mode is only valid for negative feedback.", "INVALID_FLAG_VALUE", "Remove --failure-mode or switch to --negative.");
             }
-            parseAssetRef(ref);
-            if (args.positive && args.negative) {
-                throw new UsageError("Specify either --positive or --negative, not both.");
+            const cfg = loadConfig();
+            const allowedModes = cfg.feedback?.allowedFailureModes ?? FEEDBACK_FAILURE_MODES;
+            if (allowedModes.length > 0 && !allowedModes.includes(failureMode)) {
+                throw new UsageError(`Invalid --failure-mode "${failureMode}". Accepted values: ${allowedModes.join(", ")}.`, "INVALID_FLAG_VALUE", `Use one of: ${allowedModes.join(", ")}`);
             }
-            if (!args.positive && !args.negative) {
-                throw new UsageError("Specify --positive or --negative.");
+        }
+        if (args.negative === true && !reason?.trim()) {
+            // F-3 / #384: Default requireReason is now true. Load config to allow
+            // operators to opt out via feedback.requireReason: false in akm.json.
+            const cfg = loadConfig();
+            const requireReason = cfg.feedback?.requireReason ?? true; // Default: true (F-3 / #384)
+            if (requireReason) {
+                throw new UsageError("Negative feedback requires --reason (structured failure signals are needed for distillation). " +
+                    "Use --failure-mode for a curated taxonomy or --reason for free text. " +
+                    "Set feedback.requireReason: false in akm.json to downgrade to a warning.", "MISSING_REQUIRED_ARGUMENT", `Hint: akm feedback ${ref} --negative --reason "..." [--failure-mode incorrect|outdated|dangerous|incomplete|redundant]`);
             }
-            const signal = args.positive ? "positive" : "negative";
-            const reason = args.reason;
-            // F-3 / #384: Validate --failure-mode against the curated enum.
-            const failureMode = args["failure-mode"]?.trim() || undefined;
-            if (failureMode) {
-                if (args.positive) {
-                    throw new UsageError("--failure-mode is only valid for negative feedback.", "INVALID_FLAG_VALUE", "Remove --failure-mode or switch to --negative.");
-                }
-                const cfg = loadConfig();
-                const allowedModes = cfg.feedback?.allowedFailureModes ?? FEEDBACK_FAILURE_MODES;
-                if (allowedModes.length > 0 && !allowedModes.includes(failureMode)) {
-                    throw new UsageError(`Invalid --failure-mode "${failureMode}". Accepted values: ${allowedModes.join(", ")}.`, "INVALID_FLAG_VALUE", `Use one of: ${allowedModes.join(", ")}`);
-                }
+            else {
+                warn("Warning: negative feedback without --reason provides less distillation signal.");
             }
-            if (args.negative === true && !reason?.trim()) {
-                // F-3 / #384: Default requireReason is now true. Load config to allow
-                // operators to opt out via feedback.requireReason: false in akm.json.
-                const cfg = loadConfig();
-                const requireReason = cfg.feedback?.requireReason ?? true; // Default: true (F-3 / #384)
-                if (requireReason) {
-                    throw new UsageError("Negative feedback requires --reason (structured failure signals are needed for distillation). " +
-                        "Use --failure-mode for a curated taxonomy or --reason for free text. " +
-                        "Set feedback.requireReason: false in akm.json to downgrade to a warning.", "MISSING_REQUIRED_ARGUMENT", `Hint: akm feedback ${ref} --negative --reason "..." [--failure-mode incorrect|outdated|dangerous|incomplete|redundant]`);
-                }
-                else {
-                    warn("Warning: negative feedback without --reason provides less distillation signal.");
-                }
+        }
+        const rawTags = parseAllFlagValues("--tag");
+        const validatedTags = validateFeedbackTags(rawTags);
+        const metadataObj = {
+            signal,
+            ...(reason?.trim() ? { reason: reason.trim() } : {}),
+            ...(failureMode ? { failureMode } : {}),
+            ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
+        };
+        const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
+        // Feedback only needs the index to exist, not to be current. A stale index
+        // is fine — the ref lookup works against any populated DB. We do NOT call
+        // ensureIndex here: it either blocks (3+ min inline reindex) or spawns a
+        // background process that holds the writer lock, causing the feedback write
+        // to spin-wait for the full reindex duration. If the DB is absent we give a
+        // clear error below rather than silently triggering a rebuild.
+        if (!fs.existsSync(getDbPath())) {
+            throw new UsageError("Index not found. Run 'akm index' first to build the index before recording feedback.", "MISSING_REQUIRED_ARGUMENT", "akm index");
+        }
+        // Feedback writes exactly 2 rows (usage_events + utility_score). SQLite
+        // WAL mode + busy_timeout=30s handles concurrent access with an ongoing
+        // `akm improve` run without needing the application-level writer lock.
+        // The lock was originally needed to prevent feedback from racing a
+        // background reindex it spawned — now that ensureIndex is removed, holding
+        // the lock only causes feedback to block for the full improve run duration.
+        let utilityResult;
+        const db = openExistingDatabase();
+        try {
+            const entryId = findEntryIdByRef(db, ref);
+            if (entryId === undefined) {
+                throw new UsageError(`Ref "${ref}" is not in the index. ` +
+                    "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
             }
-            const rawTags = parseAllFlagValues("--tag");
-            const validatedTags = validateFeedbackTags(rawTags);
-            const metadataObj = {
+            // Persist the feedback signal into usage_events. For positive signals,
+            // the EMA utility score is updated immediately on the next read path.
+            // For negative signals, the score is adjusted the next time `akm index`
+            // runs — the signal is durable in the DB but does NOT suppress ranking
+            // in search results until after reindexing.
+            insertUsageEvent(db, {
+                event_type: "feedback",
+                entry_ref: ref,
+                entry_id: entryId,
                 signal,
-                ...(reason?.trim() ? { reason: reason.trim() } : {}),
-                ...(failureMode ? { failureMode } : {}),
-                ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
-            };
-            const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
-            const utilityResult = await withIndexWriterLease({ purpose: "feedback-write" }, async () => {
-                // Feedback is itself an index.db writer, so it must not spawn a detached
-                // reindex and then compete with it for the same database file.
-                const sources = resolveSourceEntries();
-                if (sources.length > 0) {
-                    await ensureIndex(sources[0].path, { mode: "blocking" });
-                }
-                let scopedUtilityResult;
-                const db = openExistingDatabase();
-                try {
-                    const entryId = findEntryIdByRef(db, ref);
-                    if (entryId === undefined) {
-                        throw new UsageError(`Ref "${ref}" is not in the index. ` +
-                            "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
-                    }
-                    // Persist the feedback signal into usage_events. For positive signals,
-                    // the EMA utility score is updated immediately on the next read path.
-                    // For negative signals, the score is adjusted the next time `akm index`
-                    // runs — the signal is durable in the DB but does NOT suppress ranking
-                    // in search results until after reindexing.
-                    insertUsageEvent(db, {
-                        event_type: "feedback",
-                        entry_ref: ref,
-                        entry_id: entryId,
-                        signal,
-                        metadata: metadataStr,
-                    });
-                    // Apply feedback-derived utility score adjustment immediately so that
-                    // positive/negative signals influence search ranking without requiring
-                    // a full reindex. We query the total accumulated feedback counts from
-                    // usage_events so the delta reflects the entire signal history.
-                    // Uses MemRL bounded-step EMA (F-5 / #386, arXiv:2601.03192).
-                    try {
-                        const { pos, neg } = countFeedbackSignals(db, entryId);
-                        scopedUtilityResult = applyFeedbackToUtilityScore(db, entryId, pos, neg);
-                    }
-                    catch {
-                        // best-effort — feedback recording succeeds even if utility update fails
-                    }
-                }
-                finally {
-                    closeDatabase(db);
-                }
-                return scopedUtilityResult;
+                metadata: metadataStr,
             });
-            appendEvent({
-                eventType: "feedback",
-                ref,
-                metadata: metadataObj,
-            });
-            // F-5 / #386: When a high-utility asset crosses below the review threshold,
-            // auto-create a review-needed escalation proposal so a human can confirm
-            // whether the negative feedback is valid before the asset falls out of
-            // the improve loop. Best-effort — failure is logged but does not fail the
-            // feedback command.
-            // Emit a structured event rather than a proposal so the review-needed
-            // signal is queryable via `akm events list --type improve_review_needed`
-            // without risking accidental asset overwrite if the proposal is accepted.
-            if (utilityResult?.crossedReviewThreshold) {
-                try {
-                    appendEvent({
-                        eventType: "improve_review_needed",
-                        ref,
-                        metadata: {
-                            previousUtility: utilityResult.previousUtility,
-                            nextUtility: utilityResult.nextUtility,
-                            reason: reason?.trim() ?? null,
-                            failureMode: failureMode ?? null,
-                        },
-                    });
-                }
-                catch (escalationErr) {
-                    warn(`[feedback] Could not emit review-needed event for ${ref}: ${escalationErr instanceof Error ? escalationErr.message : String(escalationErr)}`);
-                }
+            // Apply feedback-derived utility score adjustment immediately so that
+            // positive/negative signals influence search ranking without requiring
+            // a full reindex. We query the total accumulated feedback counts from
+            // usage_events so the delta reflects the entire signal history.
+            // Uses MemRL bounded-step EMA (F-5 / #386, arXiv:2601.03192).
+            try {
+                const { pos, neg } = countFeedbackSignals(db, entryId);
+                utilityResult = applyFeedbackToUtilityScore(db, entryId, pos, neg);
+            }
+            catch {
+                // best-effort — feedback recording succeeds even if utility update fails
+            }
+        }
+        finally {
+            closeDatabase(db);
+        }
+        appendEvent({
+            eventType: "feedback",
+            ref,
+            metadata: metadataObj,
+        });
+        // F-5 / #386: When a high-utility asset crosses below the review threshold,
+        // auto-create a review-needed escalation proposal so a human can confirm
+        // whether the negative feedback is valid before the asset falls out of
+        // the improve loop. Best-effort — failure is logged but does not fail the
+        // feedback command.
+        // Emit a structured event rather than a proposal so the review-needed
+        // signal is queryable via `akm events list --type improve_review_needed`
+        // without risking accidental asset overwrite if the proposal is accepted.
+        if (utilityResult?.crossedReviewThreshold) {
+            try {
+                appendEvent({
+                    eventType: "improve_review_needed",
+                    ref,
+                    metadata: {
+                        previousUtility: utilityResult.previousUtility,
+                        nextUtility: utilityResult.nextUtility,
+                        reason: reason?.trim() ?? null,
+                        failureMode: failureMode ?? null,
+                    },
+                });
             }
-            // Phase 7A / Advantage D4b: --applied-to credits a lesson. When the
-            // target is a `lesson:<name>` ref and the signal is positive, append
-            // the feedback ref to the target lesson's `lessonStrength[]`
-            // frontmatter array (dedup, idempotent). Non-lesson targets are
-            // ignored. Failures here are warnings — feedback recording is the
-            // primary contract and must not regress on lesson-write errors.
-            const appliedToRaw = args["applied-to"]?.trim();
-            let appliedToResult = null;
-            if (appliedToRaw && signal === "positive") {
-                try {
-                    const parsedApplied = parseAssetRef(appliedToRaw);
-                    if (parsedApplied.type === "lesson") {
-                        const updated = appendLessonStrength(parsedApplied.type, parsedApplied.name, ref);
-                        if (updated) {
-                            appliedToResult = { lessonRef: appliedToRaw, strength: updated.strength };
-                        }
+            catch (escalationErr) {
+                warn(`[feedback] Could not emit review-needed event for ${ref}: ${escalationErr instanceof Error ? escalationErr.message : String(escalationErr)}`);
+            }
+        }
+        // Phase 7A / Advantage D4b: --applied-to credits a lesson. When the
+        // target is a `lesson:<name>` ref and the signal is positive, append
+        // the feedback ref to the target lesson's `lessonStrength[]`
+        // frontmatter array (dedup, idempotent). Non-lesson targets are
+        // ignored. Failures here are warnings — feedback recording is the
+        // primary contract and must not regress on lesson-write errors.
+        const appliedToRaw = args["applied-to"]?.trim();
+        let appliedToResult = null;
+        if (appliedToRaw && signal === "positive") {
+            try {
+                const parsedApplied = parseAssetRef(appliedToRaw);
+                if (parsedApplied.type === "lesson") {
+                    const updated = appendLessonStrength(parsedApplied.type, parsedApplied.name, ref);
+                    if (updated) {
+                        appliedToResult = { lessonRef: appliedToRaw, strength: updated.strength };
                     }
                 }
-                catch (err) {
-                    warn(`[feedback] --applied-to failed for ${appliedToRaw}: ${err instanceof Error ? err.message : String(err)}`);
-                }
             }
-            else if (appliedToRaw && signal !== "positive") {
-                warn("[feedback] --applied-to is ignored without --positive; lesson credit is only recorded on positive signals.");
+            catch (err) {
+                warn(`[feedback] --applied-to failed for ${appliedToRaw}: ${err instanceof Error ? err.message : String(err)}`);
             }
-            output("feedback", {
-                ok: true,
-                ref,
-                signal,
-                reason: reason?.trim() ?? null,
-                failureMode: failureMode ?? null,
-                tags: validatedTags,
-                ...(appliedToResult
-                    ? { appliedTo: { ref: appliedToResult.lessonRef, lessonStrength: appliedToResult.strength } }
-                    : {}),
-            });
+        }
+        else if (appliedToRaw && signal !== "positive") {
+            warn("[feedback] --applied-to is ignored without --positive; lesson credit is only recorded on positive signals.");
+        }
+        output("feedback", {
+            ok: true,
+            ref,
+            signal,
+            reason: reason?.trim() ?? null,
+            failureMode: failureMode ?? null,
+            tags: validatedTags,
+            ...(appliedToResult
+                ? { appliedTo: { ref: appliedToResult.lessonRef, lessonStrength: appliedToResult.strength } }
+                : {}),
         });
     },
 });

package/dist/commands/graph/graph-cli.js

@@ -9,12 +9,9 @@
  * same JSON envelope (stdout/stderr/exit-code) as the inline `runWithJsonErrors`
  * form it replaces.
  */
-import { defineCommand } from "citty";
-import { hasSubcommand, parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
+import { parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
 import { akmGraphEntities, akmGraphEntity, akmGraphExport, akmGraphOrphans, akmGraphRelated, akmGraphRelations, akmGraphSummary, akmGraphUpdate, } from "./graph.js";
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
 const graphSubCommands = {
     summary: defineJsonCommand({
         meta: { name: "summary", description: "Show entity-graph counts and quality telemetry" },
@@ -118,15 +115,10 @@ const graphSubCommands = {
         },
     }),
 };
-const GRAPH_SUBCOMMAND_SET = new Set(Object.keys(graphSubCommands));
-export const graphCommand = defineCommand({
+export const graphCommand = defineGroupCommand({
     meta: { name: "graph", description: "Inspect the indexed entity graph stored in SQLite" },
     subCommands: graphSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(() => {
-            if (hasSubcommand(args, GRAPH_SUBCOMMAND_SET))
-                return;
-            output("graph-summary", akmGraphSummary());
-        });
+    defaultRun() {
+        output("graph-summary", akmGraphSummary());
     },
 });

package/dist/commands/graph/graph.js

@@ -8,7 +8,7 @@ import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { getDbPath } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
-import { closeDatabase, findEntryIdByRef, getEntryById, getEntryRefRowsForStashRoot, openDatabase, openExistingDatabase, } from "../../indexer/db/db.js";
+import { closeDatabase, findEntryIdByRef, getEntryById, getEntryRefRowsForStashRoot, openExistingDatabase, openIndexDatabase, } from "../../indexer/db/db.js";
 import { loadStoredGraphSnapshot } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { runGraphExtractionPass } from "../../indexer/graph/graph-extraction.js";
@@ -385,7 +385,7 @@ export async function akmGraphUpdate(options) {
             let db;
             const resolvedPaths = new Set();
             try {
-                db = openDatabase(dbPath);
+                db = openIndexDatabase(dbPath);
                 for (const ref of options.refs) {
                     const trimmed = ref.trim();
                     if (!trimmed)
@@ -426,7 +426,7 @@ export async function akmGraphUpdate(options) {
         let db;
         const startMs = Date.now();
         try {
-            db = openDatabase(getDbPath());
+            db = openIndexDatabase(getDbPath());
             const onProgress = (event) => {
                 if (!event.currentPath)
                     return;

package/dist/commands/health/advisories.js

@@ -0,0 +1,151 @@
+// 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/.
+/**
+ * Improve-pipeline advisories for `akm health`: projects the computed
+ * {@link ImproveHealthMetrics} plus a few direct event reads into the
+ * ordered advisory list.
+ */
+import { readEvents } from "../../core/events.js";
+import { getLatestCycleMetrics } from "../../storage/repositories/canaries-repository.js";
+import { ENRICHMENT_MINTED_FAIL_SHARE, ENRICHMENT_MINTED_WARN_SHARE, } from "./types.js";
+/**
+ * Build the improve-pipeline advisories for the health window from the already
+ * computed {@link ImproveHealthMetrics} plus a few direct event reads. Pure
+ * projection of state → advisories; emission order is preserved so the health
+ * report is byte-identical to the previous inline construction.
+ */
+export function collectImproveAdvisories(db, stateDbPath, since, improveSummary) {
+    const advisories = [];
+    // WS-2 proxy-adequacy tripwire: surface any outcome_proxy_inverted events
+    // in the health window as an advisory so operators know when the 0.10+
+    // rich in-session signal is no longer deferrable.
+    const proxyInvertedEvents = readEvents({ since, type: "outcome_proxy_inverted" }, { dbPath: stateDbPath }).events;
+    if (proxyInvertedEvents.length > 0) {
+        const lastEvent = proxyInvertedEvents[proxyInvertedEvents.length - 1];
+        const correlation = typeof lastEvent.metadata?.correlation === "number" ? lastEvent.metadata.correlation.toFixed(3) : "unknown";
+        advisories.push({
+            name: "outcome-proxy-adequacy",
+            status: "warn",
+            kind: "deterministic",
+            confidence: "high",
+            message: `WS-2 outcome proxy inverted (${proxyInvertedEvents.length} event(s) in window). ` +
+                `corr(outcome_score, accepted_change_rate) = ${correlation} < −0.3. ` +
+                "Popular assets are also the most-needing-improvement assets — " +
+                "the retrieval-based proxy is inverted. " +
+                "The 0.10+ rich in-session outcome signal is no longer deferrable. See plan §WS-2.",
+        });
+    }
+    // Two-tailed companion: a proxy that decays to noise (|corr| < 0.1 at scale)
+    // is as much a failure as an inverted one — it just fails silently.
+    const proxyDeadEvents = readEvents({ since, type: "outcome_proxy_dead" }, { dbPath: stateDbPath, db }).events;
+    if (proxyDeadEvents.length > 0) {
+        const lastEvent = proxyDeadEvents[proxyDeadEvents.length - 1];
+        const correlation = typeof lastEvent.metadata?.correlation === "number" ? lastEvent.metadata.correlation.toFixed(3) : "unknown";
+        advisories.push({
+            name: "outcome-proxy-dead",
+            status: "warn",
+            kind: "deterministic",
+            confidence: "high",
+            message: `WS-2 outcome proxy is DEAD (${proxyDeadEvents.length} event(s) in window). ` +
+                `|corr(outcome_score, accepted_change_rate)| = ${correlation} < 0.1 at n ≥ 500. ` +
+                "outcome_score is statistically unrelated to improvement outcomes — " +
+                "treat outcome-derived rank contributions as noise until a real usage/outcome signal lands.",
+        });
+    }
+    // Salience-distribution collapse: Gini below the uniform baseline means
+    // ranking no longer discriminates between assets.
+    if (improveSummary.degradation?.salienceUniformityFlagged) {
+        advisories.push({
+            name: "salience-uniformity-collapse",
+            status: "warn",
+            kind: "deterministic",
+            confidence: "high",
+            message: `Salience distribution collapsed toward uniform: top-100 retrieval_salience Gini = ` +
+                `${improveSummary.degradation.corpusCentroidDistance} < 0.08 (uniform baseline ≈ 0.1). ` +
+                "Ranking currently carries little to no discrimination between assets.",
+        });
+    }
+    // Enrichment-vs-minting policy: enrichment lanes edit existing assets;
+    // a rising minted share means a lane is generating new content instead.
+    const minting = improveSummary.enrichmentMinting;
+    if (minting && Number.isFinite(minting.share) && minting.share > ENRICHMENT_MINTED_WARN_SHARE) {
+        advisories.push({
+            name: "enrichment-lane-minting",
+            status: minting.share > ENRICHMENT_MINTED_FAIL_SHARE ? "fail" : "warn",
+            kind: "deterministic",
+            confidence: "high",
+            message: `Enrichment lanes minted ${minting.minted} NEW asset(s) vs ${minting.updated} update(s) ` +
+                `(${Math.round(minting.share * 100)}% minted, threshold ${Math.round(ENRICHMENT_MINTED_WARN_SHARE * 100)}%). ` +
+                "Enrichment-classed lanes (proactive/high-salience/high-retrieval/signal-delta) are ratified to edit " +
+                "existing assets only — new-asset generation belongs to the signal-gated minting lanes.",
+        });
+    }
+    // Churn: accepted proposals far exceeding distinct touched refs means the
+    // loop is repeatedly rewriting the same assets, not covering the corpus.
+    if (Number.isFinite(improveSummary.coverage.churnRatio) && improveSummary.coverage.churnRatio > 1.5) {
+        advisories.push({
+            name: "improve-churn-ratio",
+            status: "warn",
+            kind: "deterministic",
+            confidence: "high",
+            message: `Improve churn ratio ${improveSummary.coverage.churnRatio} > 1.5: ` +
+                `${improveSummary.coverage.acceptedProposals} accepted proposals touched only ` +
+                `${improveSummary.coverage.distinctRefs} distinct assets in the window — ` +
+                "repeated rewrites of the same refs count as churn, not coverage.",
+        });
+    }
+    // R5 collapse/churn detector: surface any collapse_detector_alert events
+    // in the health window, plus the latest cycle row's headline numbers so
+    // the operator can act without opening the DB. `unknown` when the detector
+    // has never produced a cycle row (no consolidate/recombine work yet).
+    try {
+        // Reuse the already-open state.db handle (readEvents supports a
+        // borrowed connection) — no extra open/migrate/close per health call.
+        const collapseAlertEvents = readEvents({ since, type: "collapse_detector_alert" }, { dbPath: stateDbPath, db }).events;
+        const latestCycle = getLatestCycleMetrics(db);
+        const cycleSummary = latestCycle
+            ? `Latest cycle (${latestCycle.ts}, ${latestCycle.pass}): mean canary recall ${latestCycle.mean_recall.toFixed(3)}, ` +
+                `distinct-content ratio ${latestCycle.distinct_content_ratio.toFixed(3)}, ` +
+                `${latestCycle.accepted_actions} accepted action(s).`
+            : "";
+        if (collapseAlertEvents.length > 0) {
+            const kinds = [...new Set(collapseAlertEvents.map((e) => String(e.metadata?.kind ?? "unknown")))];
+            const collapseKinds = kinds.filter((k) => k.startsWith("collapse"));
+            advisories.push({
+                name: "collapse-churn-detector",
+                status: "warn",
+                kind: "deterministic",
+                // Collapse kinds are measured, not inferred; churn/merge-floor
+                // volume thresholds are still being tuned (design doc §7).
+                confidence: collapseKinds.length > 0 ? "high" : "medium",
+                message: `R5 detector fired ${collapseAlertEvents.length} alert(s) in window (kinds: ${kinds.join(", ")}). ` +
+                    `${cycleSummary} See docs/design/improve-collapse-churn-detector-design.md §6.3 runbook queries.`,
+            });
+        }
+        else if (latestCycle) {
+            advisories.push({
+                name: "collapse-churn-detector",
+                status: "pass",
+                kind: "deterministic",
+                confidence: "high",
+                message: `No collapse/churn alerts in window. ${cycleSummary}`,
+            });
+        }
+        else {
+            advisories.push({
+                name: "collapse-churn-detector",
+                status: "unknown",
+                kind: "deterministic",
+                confidence: "high",
+                message: "No detector cycle rows yet — the collapse/churn detector runs only on improve cycles " +
+                    "where consolidate/recombine did work (synthesis lanes may be idle).",
+            });
+        }
+    }
+    catch {
+        // Table may predate migration 016 in odd mixed-version setups — advisory
+        // is best-effort and must never fail the health command.
+    }
+    return advisories;
+}