akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/feedback-cli.js

@@ -3,17 +3,25 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.js";
-import { parseAssetRef } from "../core/asset/asset-ref.js";
+import { makeBundleRef, parseBundleRef } from "../core/asset/asset-ref.js";
 import { assembleAsset } from "../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../core/asset/frontmatter.js";
-import { writeFileAtomic } from "../core/common.js";
+import { conceptIdFromTypeName, parseRefInput } from "../core/asset/resolve-ref.js";
+import { isWithin, 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 { resolveMutationTarget } from "../core/mutation-target.js";
 import { getDbPath } from "../core/paths.js";
+import { withStateDb } from "../core/state-db.js";
 import { warn } from "../core/warn.js";
-import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, getEntryFilePathById, openExistingDatabase, } from "../indexer/db/db.js";
-import { countFeedbackSignals, insertUsageEvent } from "../indexer/usage/usage-events.js";
+import { withWriteTargetMutation } from "../core/write-source.js";
+import { resolveSourceEntries } from "../indexer/search/search-source.js";
+import { countFeedbackSignals, insertUsageEvent, resolveUsageEventSource } from "../indexer/usage/usage-events.js";
+import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
+import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
+import { findEntryIdByRef, getEntryFilePathById, getItemRefById, } from "../storage/repositories/index-entries-repository.js";
+import { applyFeedbackToUtilityScore } from "../storage/repositories/index-utility-repository.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
 const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
 const MAX_FEEDBACK_TAGS = 10;
@@ -52,31 +60,68 @@ function validateFeedbackTags(raw) {
  * an existing asset — the same pattern memory-inference uses for
  * `inferenceProcessed`.
  */
-function appendLessonStrength(type, name, feedbackRef) {
-    const ref = `${type}:${name}`;
+function appendLessonStrength(refInput, feedbackRef) {
+    // Canonical conceptId (`lessons/<name>`, D-R3): `findEntryIdByRef` keys on
+    // the stored `item_ref`.
+    const conceptId = conceptIdFromTypeName(refInput.type, refInput.name);
+    const config = loadConfig();
     let filePath;
+    let bundleId;
     const db = openExistingDatabase();
     try {
-        const entryId = findEntryIdByRef(db, ref);
-        if (entryId === undefined) {
-            warn(`[feedback] --applied-to: lesson ${ref} is not in the index.`);
-            return null;
+        const entryId = findEntryIdByRef(db, makeBundleRef(refInput.origin, conceptId));
+        if (entryId !== undefined) {
+            const itemRef = getItemRefById(db, entryId);
+            const parsedItemRef = itemRef ? parseBundleRef(itemRef) : undefined;
+            filePath = getEntryFilePathById(db, entryId) ?? undefined;
+            bundleId = parsedItemRef?.bundle;
         }
-        const resolvedPath = getEntryFilePathById(db, entryId);
-        if (!resolvedPath) {
-            warn(`[feedback] --applied-to: cannot resolve file path for ${ref}.`);
-            return null;
-        }
-        filePath = resolvedPath;
     }
     finally {
         closeDatabase(db);
     }
-    if (!filePath || !fs.existsSync(filePath)) {
-        warn(`[feedback] --applied-to: lesson file missing on disk for ${ref}.`);
+    const requestedRef = makeBundleRef(refInput.origin, conceptId);
+    if (!filePath || !bundleId || !fs.existsSync(filePath)) {
+        warn(`[feedback] --applied-to: lesson ${requestedRef} is not in the index or is missing on disk.`);
+        return null;
+    }
+    const resolved = resolveMutationTarget(config, { ...refInput, origin: bundleId });
+    if (!isWithin(filePath, resolved.target.source.path)) {
+        throw new UsageError(`Resolved lesson ${requestedRef} is outside bundle "${bundleId}".`);
+    }
+    fs.lstatSync(filePath);
+    const initialUpdate = buildLessonStrengthUpdate(fs.readFileSync(filePath), feedbackRef);
+    if (!initialUpdate.nextBytes) {
+        return { ref: makeBundleRef(bundleId, conceptId), strength: initialUpdate.strength };
+    }
+    let strength = initialUpdate.strength;
+    let mutationStarted = false;
+    try {
+        withWriteTargetMutation(resolved.target, [filePath], {
+            ignored: "reject",
+            purpose: "feedback-lesson-credit",
+            message: `Update ${makeBundleRef(bundleId, conceptId)}`,
+        }, () => {
+            const stat = fs.lstatSync(filePath);
+            const update = buildLessonStrengthUpdate(fs.readFileSync(filePath), feedbackRef);
+            strength = update.strength;
+            if (!update.nextBytes)
+                return;
+            mutationStarted = true;
+            // Preserve the existing file's permission bits (markdown assets are typically 0o644).
+            writeFileAtomic(filePath, update.nextBytes, stat.mode & 0o777);
+        });
+    }
+    catch (err) {
+        if (mutationStarted)
+            throw err;
+        warn(`[feedback] --applied-to: failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
-    const raw = fs.readFileSync(filePath, "utf8");
+    return { ref: makeBundleRef(bundleId, conceptId), strength };
+}
+function buildLessonStrengthUpdate(rawBytes, feedbackRef) {
+    const raw = rawBytes.toString("utf8");
     const parsed = parseFrontmatter(raw);
     const data = { ...parsed.data };
     const existing = data.lessonStrength;
@@ -86,7 +131,6 @@ function appendLessonStrength(type, name, feedbackRef) {
             ? [existing.trim()]
             : [];
     if (strengthList.includes(feedbackRef)) {
-        // Already credited — idempotent no-op.
         return { strength: strengthList.length };
     }
     strengthList.push(feedbackRef);
@@ -94,40 +138,76 @@ function appendLessonStrength(type, name, feedbackRef) {
     const block = parseFrontmatterBlock(raw);
     const body = block?.content ?? raw;
     const next = assembleAsset(data, body);
-    try {
-        // Preserve the existing file's permission bits (markdown assets are
-        // typically 0o644); writeFileAtomic defaults to 0o600 otherwise.
-        const mode = fs.statSync(filePath).mode & 0o777;
-        writeFileAtomic(filePath, next, mode);
-    }
-    catch (err) {
-        warn(`[feedback] --applied-to: failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
-        return null;
-    }
-    return { strength: strengthList.length };
+    const nextBytes = Buffer.from(next);
+    return rawBytes.equals(nextBytes) ? { strength: strengthList.length } : { strength: strengthList.length, nextBytes };
+}
+/**
+ * Persist the feedback usage-event (state.db) and immediately fold it into the
+ * entry's MemRL utility score (index.db). Chunk-8 WI-8.3: usage_events lives in
+ * state.db; entries + utility_scores stay in `indexDb`. BOTH positive and
+ * negative signals apply the EMA utility update unconditionally and
+ * immediately when the source is user-attributed — no `akm index` run is
+ * required for either signal to affect search ranking. Uses the bounded-step
+ * EMA policy (F-5 / #386, arXiv:2601.03192).
+ *
+ * The update is intentionally SKIPPED for non-`user` event sources (`improve`,
+ * `task`, `audit`, `unknown`) — an anti-self-reinforcement guard that stops an
+ * agent or automated pipeline from boosting its own picks. This is by design
+ * and must not be removed; R-034 only asks that the skip be surfaced to the
+ * caller rather than passing silently. Best-effort: a utility-update failure
+ * never fails the feedback record.
+ */
+function recordFeedbackUsage(indexDb, entryId, durableEntryRef, signal, metadataStr) {
+    let utilityResult;
+    let rankingUpdateApplied = false;
+    let rankingUpdateSkippedReason;
+    const eventSource = resolveUsageEventSource();
+    withStateDb((stateDb) => {
+        insertUsageEvent(stateDb, {
+            event_type: "feedback",
+            entry_ref: durableEntryRef,
+            entry_id: entryId,
+            signal,
+            metadata: metadataStr,
+            source: eventSource,
+        });
+        if (eventSource !== "user") {
+            rankingUpdateSkippedReason =
+                `feedback source is "${eventSource}", not "user" — ranking updates only apply to user-attributed ` +
+                    "feedback (anti-self-reinforcement guard; set AKM_EVENT_SOURCE=user to record as user demand).";
+            return;
+        }
+        try {
+            const { pos, neg } = countFeedbackSignals(stateDb, entryId);
+            utilityResult = applyFeedbackToUtilityScore(indexDb, entryId, pos, neg);
+            rankingUpdateApplied = true;
+        }
+        catch (err) {
+            // best-effort — feedback recording succeeds even if utility update fails
+            rankingUpdateSkippedReason = `utility update failed: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    });
+    return { utilityResult, rankingUpdateApplied, rankingUpdateSkippedReason };
 }
 // ── Command definition ────────────────────────────────────────────────────────
 export const feedbackCommand = defineJsonCommand({
     meta: {
         name: "feedback",
-        description: "Record positive or negative feedback for any indexed stash asset.\n\n" +
-            "Positive feedback boosts an asset's EMA utility score, making it rank higher\n" +
-            "in future searches without requiring a full reindex.\n\n" +
-            "Negative feedback records a negative signal in usage_events and state.db events.\n" +
-            "It does NOT immediately lower the asset's ranking — the EMA utility score is\n" +
-            "updated the next time `akm index` runs (incremental or full). Run `akm index`\n" +
-            "after recording negative feedback to have it reflected in search results.",
+        description: "Record positive or negative feedback for any indexed bundle asset.\n\n" +
+            "Both signals adjust the asset's usefulness score right away, in the same\n" +
+            "process: positive feedback raises it, negative lowers it, and recent\n" +
+            "feedback counts for more than old feedback. No reindex is needed — the new\n" +
+            "score affects ranking starting with the very next `akm search`.",
     },
     args: {
         // Optional in citty so run() is invoked even when omitted; we re-validate
         // and throw a structured UsageError below so exit code is 2 (USAGE) rather
         // than citty's default 0 (help banner).
-        ref: { type: "positional", description: "Asset ref (type:name)", required: false },
+        ref: { type: "positional", description: "Asset ref ([bundle//]conceptId, e.g. lessons/deploy)", required: false },
         positive: { type: "boolean", description: "Record positive feedback (boosts ranking immediately)", default: false },
         negative: {
             type: "boolean",
-            description: "Record negative feedback (suppresses ranking after next `akm index`). " +
-                "Reindexing is required for the signal to affect search results.",
+            description: "Record negative feedback (lowers ranking immediately, no reindex needed).",
             default: false,
         },
         reason: {
@@ -136,7 +216,7 @@ export const feedbackCommand = defineJsonCommand({
         },
         "failure-mode": {
             type: "string",
-            description: `Structured failure-mode taxonomy for negative feedback (F-3 / #384). ` +
+            description: "Structured failure-mode taxonomy for negative feedback. " +
                 `Accepted values: ${FEEDBACK_FAILURE_MODES.join(", ")}. ` +
                 "Stored alongside --reason in event metadata for aggregation by the distill pipeline.",
         },
@@ -146,17 +226,18 @@ export const feedbackCommand = defineJsonCommand({
         },
         "applied-to": {
             type: "string",
-            description: "Credit a lesson that helped resolve this task. Accepts a `lesson:<name>` ref. " +
+            description: "Credit a lesson that helped resolve this task. Accepts a `lessons/<name>` ref. " +
                 "When combined with --positive, appends this feedback ref to the target lesson's " +
-                "`lessonStrength[]` frontmatter array (dedup, idempotent). Ignored on non-lesson targets.",
+                "`lessonStrength[]` frontmatter array (dedup, idempotent). A non-lesson target or a " +
+                "missing --positive produces a warning rather than silently doing nothing.",
         },
     },
     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.");
+            throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skills/deploy` and either --positive or --negative.");
         }
-        parseAssetRef(ref);
+        const parsedRef = parseBundleRef(ref);
         if (args.positive && args.negative) {
             throw new UsageError("Specify either --positive or --negative, not both.");
         }
@@ -216,44 +297,46 @@ export const feedbackCommand = defineJsonCommand({
         // 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;
+        let rankingUpdateApplied = false;
+        let rankingUpdateSkippedReason;
+        let durableRef = ref;
         const db = openExistingDatabase();
         try {
-            const entryId = findEntryIdByRef(db, ref);
+            const config = loadConfig();
+            const sources = resolveSourceEntries(undefined, config);
+            const requestedSource = parsedRef.bundle ? resolveSourcesForOrigin(parsedRef.bundle, sources)[0] : undefined;
+            if (parsedRef.bundle && !requestedSource) {
+                throw new UsageError(`Source "${parsedRef.bundle}" is not configured.`, "INVALID_FLAG_VALUE");
+            }
+            const lookupRef = makeBundleRef(parsedRef.bundle, parsedRef.conceptId);
+            const entryId = findEntryIdByRef(db, lookupRef, requestedSource?.path);
             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);
-                utilityResult = applyFeedbackToUtilityScore(db, entryId, pos, neg);
-            }
-            catch {
-                // best-effort — feedback recording succeeds even if utility update fails
-            }
+            // Persist the feedback signal into usage_events. Both positive and
+            // negative signals apply the EMA utility update immediately — no
+            // `akm index` run is required for either signal to affect ranking in
+            // search results (see recordFeedbackUsage / applyFeedbackToUtilityScore).
+            // WI-8.5b: the `feedback` / `improve_review_needed` events key on the
+            // resolved entry's fully-qualified item_ref — the SAME durable key the
+            // usage_events row carries and the SAME spelling the signal-delta
+            // correlation reads (buildLatestFeedbackTsMap, collapsed to [item_ref]).
+            const itemRef = getItemRefById(db, entryId);
+            if (!itemRef)
+                throw new UsageError(`Indexed ref "${ref}" has no durable item ref.`, "INVALID_PROPOSAL");
+            durableRef = itemRef;
+            const recordResult = recordFeedbackUsage(db, entryId, itemRef, signal, metadataStr);
+            utilityResult = recordResult.utilityResult;
+            rankingUpdateApplied = recordResult.rankingUpdateApplied;
+            rankingUpdateSkippedReason = recordResult.rankingUpdateSkippedReason;
         }
         finally {
             closeDatabase(db);
         }
         appendEvent({
             eventType: "feedback",
-            ref,
+            ref: durableRef,
             metadata: metadataObj,
         });
         // F-5 / #386: When a high-utility asset crosses below the review threshold,
@@ -262,13 +345,13 @@ export const feedbackCommand = defineJsonCommand({
         // 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.
+        // signal doesn't risk an accidental asset overwrite if the proposal is
+        // accepted.
         if (utilityResult?.crossedReviewThreshold) {
             try {
                 appendEvent({
                     eventType: "improve_review_needed",
-                    ref,
+                    ref: durableRef,
                     metadata: {
                         previousUtility: utilityResult.previousUtility,
                         nextUtility: utilityResult.nextUtility,
@@ -282,25 +365,33 @@ export const feedbackCommand = defineJsonCommand({
             }
         }
         // Phase 7A / Advantage D4b: --applied-to credits a lesson. When the
-        // target is a `lesson:<name>` ref and the signal is positive, append
+        // target is a `lessons/<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.
+        // frontmatter array (dedup, idempotent). Non-lesson targets are REJECTED
+        // with a loud warning (R-033b) rather than silently doing nothing.
+        // 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") {
+            let parsedApplied;
             try {
-                const parsedApplied = parseAssetRef(appliedToRaw);
+                parsedApplied = parseRefInput(appliedToRaw);
+            }
+            catch (err) {
+                warn(`[feedback] --applied-to failed for ${appliedToRaw}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (parsedApplied) {
                 if (parsedApplied.type === "lesson") {
-                    const updated = appendLessonStrength(parsedApplied.type, parsedApplied.name, ref);
+                    const updated = appendLessonStrength(parsedApplied, durableRef);
                     if (updated) {
-                        appliedToResult = { lessonRef: appliedToRaw, strength: updated.strength };
+                        appliedToResult = { lessonRef: updated.ref, strength: updated.strength };
                     }
                 }
-            }
-            catch (err) {
-                warn(`[feedback] --applied-to failed for ${appliedToRaw}: ${err instanceof Error ? err.message : String(err)}`);
+                else {
+                    warn(`[feedback] --applied-to ${appliedToRaw} was ignored: it resolves to a "${parsedApplied.type}" asset, ` +
+                        "not a lesson. Only `lessons/<name>` refs can be credited via --applied-to.");
+                }
             }
         }
         else if (appliedToRaw && signal !== "positive") {
@@ -313,6 +404,9 @@ export const feedbackCommand = defineJsonCommand({
             reason: reason?.trim() ?? null,
             failureMode: failureMode ?? null,
             tags: validatedTags,
+            rankingUpdate: rankingUpdateApplied
+                ? { applied: true }
+                : { applied: false, reason: rankingUpdateSkippedReason ?? "unknown" },
             ...(appliedToResult
                 ? { appliedTo: { ref: appliedToResult.lessonRef, lessonStrength: appliedToResult.strength } }
                 : {}),

package/dist/commands/health/accept-rate.js

@@ -0,0 +1,58 @@
+// 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/.
+/**
+ * Per-proposal-source accept-rate metrics, folded into `akm health --report`
+ * (0.9.0 CLI overhaul, S3).
+ *
+ * Provides the core self-measurement metric for recursive self-improvement:
+ * if reflect proposals are accepted at 20% and distill proposals at 60%,
+ * that guides resource allocation to higher-ROI generators.
+ *
+ * Previously exposed as the removed `akm history --accept-rate-by-source`
+ * flag (src/commands/sources/history.ts, F-4 / #385); `health` already reads
+ * the pending proposal queue for its own `--report` dataset, so this is the
+ * same read extended to the accepted/rejected archive.
+ */
+import { resolveStashDir } from "../../core/common.js";
+import { listProposals } from "../proposal/repository.js";
+/**
+ * Compute accept-rate-per-source metrics from the proposal store. Defaults to
+ * the configured default stash when `stashDir` is omitted (same resolution
+ * `akm health` already uses for the rest of its report).
+ */
+export function computeAcceptRateBySource(stashDir) {
+    const stash = stashDir ?? resolveStashDir();
+    const bySource = new Map();
+    const countProposals = (statuses, includeArchive) => {
+        for (const status of statuses) {
+            const proposals = listProposals(stash, { status, includeArchive });
+            for (const p of proposals) {
+                const src = p.source || "(unknown)";
+                const entry = bySource.get(src) ?? { accepted: 0, rejected: 0, pending: 0 };
+                if (status === "accepted")
+                    entry.accepted++;
+                else if (status === "rejected")
+                    entry.rejected++;
+                else
+                    entry.pending++;
+                bySource.set(src, entry);
+            }
+        }
+    };
+    countProposals(["pending"], false);
+    countProposals(["accepted", "rejected"], true);
+    return Array.from(bySource.entries())
+        .map(([source, counts]) => {
+        const decided = counts.accepted + counts.rejected;
+        return {
+            source,
+            total: decided + counts.pending,
+            accepted: counts.accepted,
+            rejected: counts.rejected,
+            pending: counts.pending,
+            acceptRate: decided > 0 ? counts.accepted / decided : null,
+        };
+    })
+        .sort((a, b) => b.total - a.total); // Most active source first
+}

package/dist/commands/health/advisories.js

@@ -77,7 +77,7 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
             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 " +
+                "Enrichment-classed lanes (proactive/high-salience/signal-delta) are ratified to edit " +
                 "existing assets only — new-asset generation belongs to the signal-gated minting lanes.",
         });
     }
@@ -98,7 +98,7 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
     // 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).
+    // has never produced a cycle row (no consolidate work yet).
     try {
         // Reuse the already-open state.db handle (readEvents supports a
         // borrowed connection) — no extra open/migrate/close per health call.
@@ -106,8 +106,7 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
         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).`
+                `distinct-content ratio ${latestCycle.distinct_content_ratio.toFixed(3)}.`
             : "";
         if (collapseAlertEvents.length > 0) {
             const kinds = [...new Set(collapseAlertEvents.map((e) => String(e.metadata?.kind ?? "unknown")))];
@@ -116,11 +115,11 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
                 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).
+                // Collapse kinds are measured, not inferred; the merge-floor
+                // volume threshold is 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.`,
+                    `${cycleSummary} See docs/architecture/specs/improve-collapse-churn-detector-design.md §6.3 runbook queries.`,
             });
         }
         else if (latestCycle) {
@@ -139,7 +138,7 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
                 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).",
+                    "where consolidate did work.",
             });
         }
     }