@winspan/claude-forge 8.54.3 → 9.2.0

package/dist/daemon/services/feedback-aggregator.d.ts

@@ -0,0 +1,179 @@
+/**
+ * FeedbackAggregator — Phase 8 of the master roadmap (master-roadmap-full-loop-
+ * 20260522-0200.md §2). Reads tool_intercepts / workflow_recommendations /
+ * injections / skill_invocations / sessions rollup metrics and folds them into
+ * a single "tuning report" structure with three classes of suggestion:
+ *
+ *   • RuleTuningSuggestion   — too-noisy or never-firing rule_intercept &
+ *                              workflow_recommend rules
+ *   • SkillTuningSuggestion  — skills that match too rarely / always fail /
+ *                              never match (stale keywords)
+ *   • KbTuningSuggestion     — KB pages that never appear in injection
+ *                              metadata, or always appear with low scores
+ *
+ * Apply contract: this service NEVER edits CLAUDE.md / skill .md / KB .md
+ * files. Every `apply_action` is whitelisted in routes/insights.ts and only
+ * writes to the `forge_config` table (so users see suggestions in the Web UI
+ * and choose to flip a flag — fully reversible via `cf config set ...`).
+ *
+ * D7 thresholds (master roadmap §1):
+ *   • C4 intercept obeyed ratio    target >= 0.70
+ *   • C8 workflow adoption ratio   target >= 0.40 (red <0.40, yellow 0.40-0.55,
+ *                                                  green >=0.55)
+ *
+ * Acceptance:
+ *   • `cf insights weekly` renders a markdown weekly report (see CLI)
+ *   • `GET /api/insights/tuning?window=7` returns suggestions + summary
+ *   • Feature flag `feedback_loop.enabled` (Phase 0) gates the endpoint —
+ *     this class never probes the flag itself; the route does.
+ */
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+export type SeverityBand = 'red' | 'yellow' | 'green';
+export interface RuleTuningSuggestion {
+    kind: 'rule_tuning';
+    rule_id: string;
+    rule_kind: 'tool_intercept' | 'workflow_recommend';
+    metric: {
+        fires_per_day: number;
+        obeyed_ratio: number;
+        override_count_7d: number;
+        /** Phase 5 only — fraction of accepted recommendations in window. */
+        accepted_ratio?: number;
+        fires_7d: number;
+    };
+    suggestion: string;
+    apply_action?: {
+        type: 'disable_rule' | 'tighten_threshold' | 'loosen_threshold';
+        payload: Record<string, unknown>;
+    };
+}
+export interface SkillTuningSuggestion {
+    kind: 'skill_tuning';
+    skill_id: string;
+    metric: {
+        matched_per_day: number;
+        success_rate: number;
+        zero_result_rate: number;
+        invocations_7d: number;
+    };
+    suggestion: string;
+    apply_action?: {
+        type: 'update_keywords' | 'disable_skill' | 'enable_skill';
+        payload: Record<string, unknown>;
+    };
+}
+export interface KbTuningSuggestion {
+    kind: 'kb_tuning';
+    page_name: string;
+    metric: {
+        cited_per_day: number;
+        avg_score: number;
+        in_top_2_count_7d: number;
+        cited_7d: number;
+    };
+    suggestion: string;
+    apply_action?: {
+        type: 'regenerate_module' | 'archive_page' | 'lower_priority';
+        payload: Record<string, unknown>;
+    };
+}
+export type TuningSuggestion = RuleTuningSuggestion | SkillTuningSuggestion | KbTuningSuggestion;
+export interface TuningReportSummary {
+    rule_violations_top: Array<{
+        rule_id: string;
+        n: number;
+    }>;
+    /**
+     * C4 — fraction of intercepts where outcome is 'obeyed' (excluding 'unknown').
+     * KPI relax: includes both real `deny` rows AND `dry_run` rehearsal rows
+     * back-filled by PostToolUseHandler — see post-tool-use.ts
+     * `maybeMarkInterceptOutcome`. This makes C4 meaningful before
+     * `pre_tool_intercept.enabled` is flipped on; UI tooltip notes the dry_run
+     * inclusion.
+     */
+    intercept_obeyed_ratio: number;
+    intercept_obeyed_band: SeverityBand;
+    /**
+     * C8 — weighted workflow recommendation acceptance ratio.
+     *   accepted          → 1.0
+     *   partial_accepted  → 0.5  (spawned a known subagent_type but not the
+     *                             recommended one)
+     *   rejected / bypassed / ignored → 0.0
+     * Denominator = total non-pending rows in window. Captures the common
+     * "main thread spawned `coder` instead of `refactor-specialist`" pattern
+     * that previously evaporated as `ignored`.
+     */
+    workflow_acceptance_ratio: number;
+    workflow_acceptance_band: SeverityBand;
+    /** C1 — KB injection rows in window (UserPromptSubmitHandler:kb). */
+    kb_inject_count: number;
+    kb_top_pages: Array<{
+        name: string;
+        cited: number;
+    }>;
+    skill_top: Array<{
+        skill_id: string;
+        n: number;
+        success_rate: number;
+    }>;
+    session_outcome: {
+        success: number;
+        partial: number;
+        failed: number;
+        abandoned: number;
+        unclassified: number;
+    };
+    /**
+     * H4 contract — per-decision counts of `tool_intercepts` rows in window.
+     * Surfaces the deny/dry_run/warn/bypass denominator split behind
+     * `intercept_obeyed_ratio` so curl/jq + future UI tooltip can see which
+     * decisions dominate. Optional / nullable for backwards-compat: pre-2026-05-27
+     * callers do not depend on these fields.
+     */
+    intercept_denied?: number | null;
+    intercept_dry_run?: number | null;
+    intercept_warn?: number | null;
+    intercept_bypass?: number | null;
+}
+export interface TuningReport {
+    generated_at: string;
+    window_days: 7 | 30;
+    suggestions: TuningSuggestion[];
+    summary: TuningReportSummary;
+}
+/** D7 master-roadmap default for workflow recommendation adoption. */
+export declare const C8_ACCEPTANCE_TARGET = 0.4;
+/** Below this is red. */
+export declare const C8_RED_BELOW = 0.4;
+/** At/above this is green. */
+export declare const C8_GREEN_AT = 0.55;
+/** Master roadmap C4 target for intercept obedience. */
+export declare const C4_OBEYED_TARGET = 0.7;
+export declare const C4_RED_BELOW = 0.5;
+export declare const C4_GREEN_AT = 0.7;
+export declare const RULE_NOISY_FIRES_PER_DAY = 5;
+export declare const RULE_OBEYED_RATIO_FLOOR = 0.3;
+export declare const RULE_OVERRIDE_FLOOR = 5;
+export declare const RULE_DEAD_FIRES_7D = 0;
+export declare const SKILL_ZERO_RESULT_THRESHOLD = 5;
+export declare const SKILL_LOW_SUCCESS_FLOOR = 0.5;
+export declare const KB_ARCHIVE_TARGET_CITES = 0;
+export declare const KB_LOW_SCORE_FLOOR = 10;
+export declare class FeedbackAggregator {
+    private storage;
+    constructor(storage: SQLiteStorage);
+    generateReport(opts?: {
+        windowDays: 7 | 30;
+    }): TuningReport;
+    private computeSummary;
+    private emptySummary;
+    private buildRuleSuggestions;
+    private buildSkillSuggestions;
+    private buildKbSuggestions;
+}
+/**
+ * Render a TuningReport as a markdown document. Used by `cf insights weekly`.
+ * Kept here (not in CLI) so the same renderer can power email digests later.
+ */
+export declare function renderReportMarkdown(report: TuningReport): string;
+//# sourceMappingURL=feedback-aggregator.d.ts.map

package/dist/daemon/services/feedback-aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-aggregator.d.ts","sourceRoot":"","sources":["../../../src/daemon/services/feedback-aggregator.ts"],"names":[],"mappings":"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"}

package/dist/daemon/services/feedback-aggregator.js

@@ -0,0 +1,455 @@
+/**
+ * FeedbackAggregator — Phase 8 of the master roadmap (master-roadmap-full-loop-
+ * 20260522-0200.md §2). Reads tool_intercepts / workflow_recommendations /
+ * injections / skill_invocations / sessions rollup metrics and folds them into
+ * a single "tuning report" structure with three classes of suggestion:
+ *
+ *   • RuleTuningSuggestion   — too-noisy or never-firing rule_intercept &
+ *                              workflow_recommend rules
+ *   • SkillTuningSuggestion  — skills that match too rarely / always fail /
+ *                              never match (stale keywords)
+ *   • KbTuningSuggestion     — KB pages that never appear in injection
+ *                              metadata, or always appear with low scores
+ *
+ * Apply contract: this service NEVER edits CLAUDE.md / skill .md / KB .md
+ * files. Every `apply_action` is whitelisted in routes/insights.ts and only
+ * writes to the `forge_config` table (so users see suggestions in the Web UI
+ * and choose to flip a flag — fully reversible via `cf config set ...`).
+ *
+ * D7 thresholds (master roadmap §1):
+ *   • C4 intercept obeyed ratio    target >= 0.70
+ *   • C8 workflow adoption ratio   target >= 0.40 (red <0.40, yellow 0.40-0.55,
+ *                                                  green >=0.55)
+ *
+ * Acceptance:
+ *   • `cf insights weekly` renders a markdown weekly report (see CLI)
+ *   • `GET /api/insights/tuning?window=7` returns suggestions + summary
+ *   • Feature flag `feedback_loop.enabled` (Phase 0) gates the endpoint —
+ *     this class never probes the flag itself; the route does.
+ */
+import { logger } from '../../core/utils/logger.js';
+import { formatError } from '../../core/utils/format.js';
+// ─── Thresholds (D7 + sensible defaults) ──────────────────────────────────
+/** D7 master-roadmap default for workflow recommendation adoption. */
+export const C8_ACCEPTANCE_TARGET = 0.4;
+/** Below this is red. */
+export const C8_RED_BELOW = 0.4;
+/** At/above this is green. */
+export const C8_GREEN_AT = 0.55;
+/** Master roadmap C4 target for intercept obedience. */
+export const C4_OBEYED_TARGET = 0.7;
+export const C4_RED_BELOW = 0.5;
+export const C4_GREEN_AT = 0.7;
+// Suggestion-emit thresholds — kept conservative for v1 so we don't drown
+// the UI in low-confidence noise. All exported so tests can drive them.
+export const RULE_NOISY_FIRES_PER_DAY = 5; // a rule firing > 5/day is "loud"
+export const RULE_OBEYED_RATIO_FLOOR = 0.3; // less than 30% obeyed → noisy
+export const RULE_OVERRIDE_FLOOR = 5; // ≥5 overrides → worth a card
+export const RULE_DEAD_FIRES_7D = 0; // never fired → suggest disable
+export const SKILL_ZERO_RESULT_THRESHOLD = 5; // ≥5 failed invocations → tag
+export const SKILL_LOW_SUCCESS_FLOOR = 0.5;
+export const KB_ARCHIVE_TARGET_CITES = 0; // page never cited in window → archive
+export const KB_LOW_SCORE_FLOOR = 10; // avg < 10 → suggest regenerate
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function sinceIso(windowDays) {
+    const ms = Date.now() - windowDays * 24 * 60 * 60 * 1000;
+    return new Date(ms).toISOString();
+}
+function sinceMs(windowDays) {
+    return Date.now() - windowDays * 24 * 60 * 60 * 1000;
+}
+function ratioBand(value, redBelow, greenAt) {
+    if (value < redBelow)
+        return 'red';
+    if (value >= greenAt)
+        return 'green';
+    return 'yellow';
+}
+// ─── Aggregator ───────────────────────────────────────────────────────────
+export class FeedbackAggregator {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    generateReport(opts = { windowDays: 7 }) {
+        const window = opts.windowDays === 30 ? 30 : 7;
+        const since = sinceIso(window);
+        const sinceMillis = sinceMs(window);
+        let summary;
+        let suggestions = [];
+        try {
+            summary = this.computeSummary(since, sinceMillis, window);
+        }
+        catch (err) {
+            logger.warn(`[FeedbackAggregator] summary failed: ${formatError(err)}`);
+            summary = this.emptySummary();
+        }
+        try {
+            suggestions = [
+                ...this.buildRuleSuggestions(since, window),
+                ...this.buildSkillSuggestions(sinceMillis, window),
+                ...this.buildKbSuggestions(since, window),
+            ];
+        }
+        catch (err) {
+            logger.warn(`[FeedbackAggregator] suggestion build failed: ${formatError(err)}`);
+        }
+        return {
+            generated_at: new Date().toISOString(),
+            window_days: window,
+            suggestions,
+            summary,
+        };
+    }
+    // ── Summary computation ────────────────────────────────────────────────
+    computeSummary(since, sinceMillis, window) {
+        // F-medium #1 (2026-05-26): all raw SQL down-sunk to FeedbackOperations.
+        // Aggregator only orchestrates + applies business rules (band thresholds,
+        // metadata_json parsing for KB top pages).
+        // C4 intercept obeyed ratio. Numerator = obeyed; denominator = obeyed +
+        // override. `unknown` excluded. KPI relax: PostToolUseHandler back-fills
+        // outcome for BOTH `deny` and `dry_run` intercept rows so this ratio is
+        // meaningful even before pre_tool_intercept.enabled is flipped on.
+        const obeyedRow = this.storage.queryInterceptObeyedSummary(since);
+        const interceptObeyed = obeyedRow.ratio;
+        // H4 contract — per-decision counts behind the obeyed ratio. See
+        // TuningReportSummary.intercept_{denied,dry_run,warn,bypass}.
+        const decisionCounts = this.storage.queryInterceptDecisionCounts(since);
+        // Top noisy intercept rules in window (by row count).
+        const ruleViolationsTop = this.storage.queryTopInterceptRuleViolations(since, 10);
+        // C8 workflow acceptance ratio — weighted by outcome strength.
+        //   accepted         → 1.0
+        //   partial_accepted → 0.5
+        //   rejected / bypassed / ignored / pending → 0.0 (pending excluded from
+        //                                                  denominator)
+        const acceptRow = this.storage.queryWorkflowAcceptanceSummary(since);
+        const workflowAccept = acceptRow.ratio;
+        // C1 KB inject count.
+        const kbInjectCount = this.storage.countKbInjections(since);
+        // KB top pages — parse metadata_json from KB injection rows. Done in JS to
+        // sidestep JSON1 portability (some sqlite builds don't have JSON1).
+        const kbPagesCounter = new Map();
+        const kbInjectionRows = this.storage.queryKbInjectionMetadata(since);
+        for (const row of kbInjectionRows) {
+            try {
+                const arr = JSON.parse(row.metadata_json);
+                if (Array.isArray(arr)) {
+                    for (const item of arr) {
+                        if (item && typeof item.name === 'string') {
+                            kbPagesCounter.set(item.name, (kbPagesCounter.get(item.name) ?? 0) + 1);
+                        }
+                    }
+                }
+            }
+            catch {
+                /* malformed metadata_json → skip */
+            }
+        }
+        const kbTopPages = Array.from(kbPagesCounter.entries())
+            .map(([name, cited]) => ({ name, cited }))
+            .sort((a, b) => b.cited - a.cited)
+            .slice(0, 10);
+        // Skill top — count by skill_id, with success rate.
+        const skillRows = this.storage.queryTopSkillInvocations(sinceMillis, 10);
+        const skillTop = skillRows.map((r) => ({
+            skill_id: r.skill_id,
+            n: r.n,
+            success_rate: r.sr ?? 0,
+        }));
+        // Session outcome distribution in window. classified_at is the canonical
+        // "when did outcome get written" timestamp.
+        const outcomeRows = this.storage.querySessionOutcomeDistribution(since);
+        const outcome = { success: 0, partial: 0, failed: 0, abandoned: 0, unclassified: 0 };
+        for (const row of outcomeRows) {
+            if (row.o === 'success' || row.o === 'partial' || row.o === 'failed' || row.o === 'abandoned') {
+                outcome[row.o] = row.n;
+            }
+            else {
+                outcome.unclassified += row.n;
+            }
+        }
+        void window; // window is captured by caller; placeholder for future per-window deltas
+        return {
+            rule_violations_top: ruleViolationsTop,
+            intercept_obeyed_ratio: interceptObeyed,
+            intercept_obeyed_band: ratioBand(interceptObeyed, C4_RED_BELOW, C4_GREEN_AT),
+            workflow_acceptance_ratio: workflowAccept,
+            workflow_acceptance_band: ratioBand(workflowAccept, C8_RED_BELOW, C8_GREEN_AT),
+            kb_inject_count: kbInjectCount,
+            kb_top_pages: kbTopPages,
+            skill_top: skillTop,
+            session_outcome: outcome,
+            intercept_denied: decisionCounts.denied,
+            intercept_dry_run: decisionCounts.dry_run,
+            intercept_warn: decisionCounts.warn,
+            intercept_bypass: decisionCounts.bypass,
+        };
+    }
+    emptySummary() {
+        return {
+            rule_violations_top: [],
+            intercept_obeyed_ratio: 0,
+            intercept_obeyed_band: 'red',
+            workflow_acceptance_ratio: 0,
+            workflow_acceptance_band: 'red',
+            kb_inject_count: 0,
+            kb_top_pages: [],
+            skill_top: [],
+            session_outcome: { success: 0, partial: 0, failed: 0, abandoned: 0, unclassified: 0 },
+            // H4 contract — emptySummary is the catch-block fallback when aggregation
+            // itself throws. Distinguished from "true zero" (returned by SQL on
+            // empty tool_intercepts) by using null. Callers (curl/jq) can tell apart
+            // "no data observed" vs "computation failed".
+            intercept_denied: null,
+            intercept_dry_run: null,
+            intercept_warn: null,
+            intercept_bypass: null,
+        };
+    }
+    // ── Rule suggestions (tool_intercepts + workflow_recommendations) ──────
+    buildRuleSuggestions(since, windowDays) {
+        const out = [];
+        // tool_intercept rules grouped by rule_id — per-rule fire count / obeyed / override.
+        const interceptRows = this.storage.queryInterceptRuleAggregates(since);
+        for (const row of interceptRows) {
+            const firesPerDay = row.fires / Math.max(1, windowDays);
+            const decided = row.obeyed + row.overrides;
+            const obeyedRatio = decided > 0 ? row.obeyed / decided : 0;
+            // Noisy + low obey → propose disabling / loosening.
+            if (firesPerDay >= RULE_NOISY_FIRES_PER_DAY && obeyedRatio < RULE_OBEYED_RATIO_FLOOR) {
+                out.push({
+                    kind: 'rule_tuning',
+                    rule_id: row.rule_id,
+                    rule_kind: 'tool_intercept',
+                    metric: {
+                        fires_per_day: round(firesPerDay, 2),
+                        obeyed_ratio: round(obeyedRatio, 2),
+                        override_count_7d: row.overrides,
+                        fires_7d: row.fires,
+                    },
+                    suggestion: `Rule "${row.rule_id}" fires ${row.fires} time(s) in the window (${round(firesPerDay, 1)}/day) ` +
+                        `but only ${Math.round(obeyedRatio * 100)}% are obeyed. Consider loosening or disabling.`,
+                    apply_action: {
+                        type: 'loosen_threshold',
+                        payload: { rule_id: row.rule_id, rule_kind: 'tool_intercept' },
+                    },
+                });
+                continue;
+            }
+            // Many overrides relative to total → worth surfacing even if obey ratio
+            // is OK; user is regularly bypassing.
+            if (row.overrides >= RULE_OVERRIDE_FLOOR && row.overrides > row.obeyed) {
+                out.push({
+                    kind: 'rule_tuning',
+                    rule_id: row.rule_id,
+                    rule_kind: 'tool_intercept',
+                    metric: {
+                        fires_per_day: round(firesPerDay, 2),
+                        obeyed_ratio: round(obeyedRatio, 2),
+                        override_count_7d: row.overrides,
+                        fires_7d: row.fires,
+                    },
+                    suggestion: `Rule "${row.rule_id}" has ${row.overrides} overrides vs ${row.obeyed} obeyed. ` +
+                        `Users routinely bypass — consider loosening or disabling.`,
+                    apply_action: {
+                        type: 'loosen_threshold',
+                        payload: { rule_id: row.rule_id, rule_kind: 'tool_intercept' },
+                    },
+                });
+            }
+        }
+        // workflow_recommend rules — emit a suggestion when accepted_ratio is low.
+        // Mirrors the summary-level C8 weighting: partial_accepted contributes 0.5
+        // so a rule that triggers lots of "tried but missed" spawns isn't unfairly
+        // tagged as ignored.
+        const workflowRows = this.storage.queryWorkflowRuleAggregates(since);
+        for (const row of workflowRows) {
+            const firesPerDay = row.fires / Math.max(1, windowDays);
+            const acceptedRatio = row.fires > 0 ? (row.accepted + row.partial * 0.5) / row.fires : 0;
+            if (firesPerDay >= 1 && acceptedRatio < C8_RED_BELOW) {
+                out.push({
+                    kind: 'rule_tuning',
+                    rule_id: row.rule_id,
+                    rule_kind: 'workflow_recommend',
+                    metric: {
+                        fires_per_day: round(firesPerDay, 2),
+                        obeyed_ratio: 0,
+                        override_count_7d: row.rejected,
+                        accepted_ratio: round(acceptedRatio, 2),
+                        fires_7d: row.fires,
+                    },
+                    suggestion: `Workflow rule "${row.rule_id}" fired ${row.fires} time(s) but only ${row.accepted} were accepted ` +
+                        `(${Math.round(acceptedRatio * 100)}%, below C8 target ${Math.round(C8_ACCEPTANCE_TARGET * 100)}%). ` +
+                        `Consider tightening the matcher or disabling.`,
+                    apply_action: {
+                        type: 'disable_rule',
+                        payload: { rule_id: row.rule_id, rule_kind: 'workflow_recommend' },
+                    },
+                });
+            }
+        }
+        return out;
+    }
+    // ── Skill suggestions ──────────────────────────────────────────────────
+    buildSkillSuggestions(sinceMillis, windowDays) {
+        const out = [];
+        const rows = this.storage.querySkillAggregates(sinceMillis);
+        for (const row of rows) {
+            const successRate = row.n > 0 ? row.succ / row.n : 0;
+            const zeroRate = row.n > 0 ? row.zero / row.n : 0;
+            const matchedPerDay = row.n / Math.max(1, windowDays);
+            if (row.zero >= SKILL_ZERO_RESULT_THRESHOLD && successRate < SKILL_LOW_SUCCESS_FLOOR) {
+                out.push({
+                    kind: 'skill_tuning',
+                    skill_id: row.skill_id,
+                    metric: {
+                        matched_per_day: round(matchedPerDay, 2),
+                        success_rate: round(successRate, 2),
+                        zero_result_rate: round(zeroRate, 2),
+                        invocations_7d: row.n,
+                    },
+                    suggestion: `Skill "${row.skill_id}" has ${row.zero} failed invocations out of ${row.n} ` +
+                        `(${Math.round(zeroRate * 100)}% failure rate). Review keywords or disable.`,
+                    apply_action: {
+                        type: 'update_keywords',
+                        payload: { skill_id: row.skill_id },
+                    },
+                });
+            }
+        }
+        return out;
+    }
+    // ── KB suggestions ─────────────────────────────────────────────────────
+    buildKbSuggestions(since, windowDays) {
+        const out = [];
+        // Aggregate cite count + score sum + top-2 count per page from
+        // injections.metadata_json. metadata is JSON array of {name, score, refs}.
+        const rows = this.storage.queryKbInjectionMetadata(since);
+        const map = new Map();
+        for (const row of rows) {
+            try {
+                const arr = JSON.parse(row.metadata_json);
+                if (!Array.isArray(arr))
+                    continue;
+                arr.forEach((item, idx) => {
+                    if (!item || typeof item.name !== 'string')
+                        return;
+                    const cur = map.get(item.name) ?? { cited: 0, scoreSum: 0, inTop2: 0 };
+                    cur.cited += 1;
+                    cur.scoreSum += typeof item.score === 'number' ? item.score : 0;
+                    if (idx < 2)
+                        cur.inTop2 += 1;
+                    map.set(item.name, cur);
+                });
+            }
+            catch {
+                /* skip malformed */
+            }
+        }
+        for (const [name, acc] of map.entries()) {
+            const avgScore = acc.cited > 0 ? acc.scoreSum / acc.cited : 0;
+            const citedPerDay = acc.cited / Math.max(1, windowDays);
+            // Page cited but always low score → suggest regenerate (probably stale).
+            if (acc.cited >= 3 && avgScore < KB_LOW_SCORE_FLOOR) {
+                out.push({
+                    kind: 'kb_tuning',
+                    page_name: name,
+                    metric: {
+                        cited_per_day: round(citedPerDay, 2),
+                        avg_score: round(avgScore, 1),
+                        in_top_2_count_7d: acc.inTop2,
+                        cited_7d: acc.cited,
+                    },
+                    suggestion: `KB page "${name}" cited ${acc.cited} time(s) but avg score is ${round(avgScore, 1)} ` +
+                        `(below ${KB_LOW_SCORE_FLOOR}). Run \`cf knowledge build --apply --module=<name>\` to refresh.`,
+                    apply_action: {
+                        type: 'regenerate_module',
+                        payload: { page_name: name },
+                    },
+                });
+            }
+        }
+        // Pages that are NEVER cited in window → suggest archive. We only know
+        // about pages that DID get cited (from metadata_json), so "never cited"
+        // is computed against a caller-supplied list. v1: skip this — it would
+        // require walking .forge-knowledge/, which the daemon does not own.
+        return out;
+    }
+}
+function round(n, digits) {
+    const m = Math.pow(10, digits);
+    return Math.round(n * m) / m;
+}
+// ─── Markdown rendering (CLI weekly report) ───────────────────────────────
+/**
+ * Render a TuningReport as a markdown document. Used by `cf insights weekly`.
+ * Kept here (not in CLI) so the same renderer can power email digests later.
+ */
+export function renderReportMarkdown(report) {
+    const lines = [];
+    lines.push(`# Forge tuning report (${report.window_days}d window)`);
+    lines.push('');
+    lines.push(`Generated at: ${report.generated_at}`);
+    lines.push('');
+    lines.push(`## KPIs`);
+    lines.push('');
+    lines.push(`- **C4 intercept obeyed**: ${pct(report.summary.intercept_obeyed_ratio)} ` +
+        `(${band(report.summary.intercept_obeyed_band)}, target ${pct(C4_OBEYED_TARGET)})`);
+    lines.push(`- **C8 workflow accepted**: ${pct(report.summary.workflow_acceptance_ratio)} ` +
+        `(${band(report.summary.workflow_acceptance_band)}, target ${pct(C8_ACCEPTANCE_TARGET)})`);
+    lines.push(`- **C1 KB injections**: ${report.summary.kb_inject_count}`);
+    const outcome = report.summary.session_outcome;
+    lines.push(`- **Session outcome**: ${outcome.success} success / ${outcome.partial} partial / ` +
+        `${outcome.failed} failed / ${outcome.abandoned} abandoned / ${outcome.unclassified} unclassified`);
+    lines.push('');
+    if (report.summary.rule_violations_top.length > 0) {
+        lines.push(`## Top intercept rules (by fire count)`);
+        lines.push('');
+        for (const r of report.summary.rule_violations_top) {
+            lines.push(`- \`${r.rule_id}\` — ${r.n} fires`);
+        }
+        lines.push('');
+    }
+    if (report.summary.kb_top_pages.length > 0) {
+        lines.push(`## Top cited KB pages`);
+        lines.push('');
+        for (const p of report.summary.kb_top_pages) {
+            lines.push(`- \`${p.name}\` — cited ${p.cited}x`);
+        }
+        lines.push('');
+    }
+    if (report.summary.skill_top.length > 0) {
+        lines.push(`## Top skill invocations`);
+        lines.push('');
+        for (const s of report.summary.skill_top) {
+            lines.push(`- \`${s.skill_id}\` — ${s.n} invocations, ${pct(s.success_rate)} success`);
+        }
+        lines.push('');
+    }
+    lines.push(`## Suggestions (${report.suggestions.length})`);
+    lines.push('');
+    if (report.suggestions.length === 0) {
+        lines.push('_No tuning suggestions — system in balance._');
+    }
+    else {
+        for (const s of report.suggestions) {
+            const id = s.kind === 'rule_tuning' ? s.rule_id : s.kind === 'skill_tuning' ? s.skill_id : s.page_name;
+            lines.push(`### [${s.kind}] ${id}`);
+            lines.push('');
+            lines.push(s.suggestion);
+            if (s.apply_action) {
+                lines.push('');
+                lines.push(`Suggested action: \`${s.apply_action.type}\` — ${JSON.stringify(s.apply_action.payload)}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+function pct(n) {
+    return `${Math.round(n * 100)}%`;
+}
+function band(b) {
+    return b === 'green' ? 'green' : b === 'yellow' ? 'yellow' : 'red';
+}
+//# sourceMappingURL=feedback-aggregator.js.map