@shrkcrft/inspector 0.1.0-alpha.1

package/dist/feedback-actions-v2.js

@@ -0,0 +1,183 @@
+/**
+ * Feedback actions v2.
+ *
+ * Wraps the feedback-ingestion output into richer action / backlog /
+ * prompt / plan shapes. The engine still does not auto-fix; humans pick
+ * the recommended next commands.
+ */
+import { ingestFeedbackFile, FeedbackSeverity, } from "./feedback-ingestion.js";
+export const FEEDBACK_ACTIONS_V2_SCHEMA = 'sharkcraft.feedback-actions/v2';
+export var FeedbackActionCategory;
+(function (FeedbackActionCategory) {
+    FeedbackActionCategory["Good"] = "good";
+    FeedbackActionCategory["Bad"] = "bad";
+    FeedbackActionCategory["Missing"] = "missing";
+    FeedbackActionCategory["Confusion"] = "confusion";
+    FeedbackActionCategory["Friction"] = "friction";
+    FeedbackActionCategory["Bug"] = "bug";
+    FeedbackActionCategory["Feature"] = "feature";
+    FeedbackActionCategory["Docs"] = "docs";
+    FeedbackActionCategory["Safety"] = "safety";
+})(FeedbackActionCategory || (FeedbackActionCategory = {}));
+function deriveCategory(tags) {
+    const t = (tags ?? []).map((x) => x.toLowerCase());
+    if (t.some((x) => x === 'safety' || x === 'security'))
+        return FeedbackActionCategory.Safety;
+    if (t.some((x) => x === 'docs' || x === 'documentation'))
+        return FeedbackActionCategory.Docs;
+    if (t.some((x) => x === 'bug'))
+        return FeedbackActionCategory.Bug;
+    if (t.some((x) => x === 'missing' || x === 'gap'))
+        return FeedbackActionCategory.Missing;
+    if (t.some((x) => x === 'confusion' || x === 'unclear'))
+        return FeedbackActionCategory.Confusion;
+    if (t.some((x) => x === 'feature'))
+        return FeedbackActionCategory.Feature;
+    if (t.some((x) => x === 'good' || x === 'praise'))
+        return FeedbackActionCategory.Good;
+    if (t.some((x) => x === 'bad' || x === 'pain' || x === 'friction'))
+        return FeedbackActionCategory.Friction;
+    return FeedbackActionCategory.Friction;
+}
+function deriveOrigin(targetArea) {
+    if (/^pack|pack-/i.test(targetArea))
+        return 'pack-specific';
+    if (/^engine|^shrk|^sharkcraft/i.test(targetArea))
+        return 'engine-generic';
+    if (/^project|^local|^repo/i.test(targetArea))
+        return 'project-specific';
+    return 'unknown';
+}
+function severityToString(sev) {
+    if (sev === FeedbackSeverity.Blocker)
+        return 'blocker';
+    if (sev === FeedbackSeverity.Major)
+        return 'major';
+    if (sev === FeedbackSeverity.Minor)
+        return 'minor';
+    return 'info';
+}
+function derivePriority(severity) {
+    if (severity === 'blocker')
+        return 'p0';
+    if (severity === 'major')
+        return 'p1';
+    if (severity === 'minor')
+        return 'p2';
+    return 'p3';
+}
+/**
+ * Derive the four-bucket improvement kind from category + origin +
+ * tags. The bucket says where the change must land, not the type of issue.
+ */
+function deriveImprovementKind(category, origin, tags) {
+    const t = tags.map((x) => x.toLowerCase());
+    if (category === FeedbackActionCategory.Docs || t.some((x) => x === 'docs' || x === 'changelog')) {
+        return 'docs';
+    }
+    if (origin === 'engine-generic')
+        return 'engine';
+    if (origin === 'pack-specific')
+        return 'pack';
+    if (origin === 'project-specific')
+        return 'local-config';
+    return 'unknown';
+}
+function findingToAction(finding, idx) {
+    const severity = severityToString(finding.severity);
+    const targetArea = finding.targetArea ?? 'unspecified';
+    const category = deriveCategory(finding.tags);
+    const origin = deriveOrigin(targetArea);
+    return {
+        id: `feedback.${idx + 1}.${targetArea.replace(/[^a-z0-9]+/gi, '-')}`,
+        originalExcerpt: finding.text.slice(0, 200),
+        paraphrase: finding.text.length > 200 ? finding.text.slice(0, 80) + '…' : finding.text,
+        category,
+        targetArea,
+        origin,
+        improvementKind: deriveImprovementKind(category, origin, finding.tags),
+        severity,
+        priority: derivePriority(severity),
+        confidence: finding.tags.length >= 2 ? 'high' : finding.tags.length === 1 ? 'medium' : 'low',
+        recommendedCommands: finding.suggestedCommands,
+        suggestedImplementationCategory: finding.tags.some((t) => /template|scaffold/.test(t)) ? 'template'
+            : finding.tags.some((t) => /docs|knowledge/.test(t)) ? 'docs'
+                : finding.tags.some((t) => /test/.test(t)) ? 'tests'
+                    : 'manual',
+        suggestedTests: [],
+        suggestedPromptSection: `Follow up on "${targetArea}" — ${finding.text.slice(0, 120)}…`,
+    };
+}
+export function buildFeedbackActionsReport(inspection, sourceFile) {
+    const report = ingestFeedbackFile(inspection.projectRoot, sourceFile);
+    return {
+        schema: FEEDBACK_ACTIONS_V2_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        sourceFile,
+        actions: report.findings.map(findingToAction),
+    };
+}
+export function buildFeedbackBacklogReport(inspection, sourceFile) {
+    const actions = buildFeedbackActionsReport(inspection, sourceFile).actions;
+    const grouped = { p0: [], p1: [], p2: [], p3: [] };
+    for (const a of actions)
+        grouped[a.priority].push(a);
+    const lines = ['# Feedback backlog', '', `Source: \`${sourceFile}\``, ''];
+    for (const p of ['p0', 'p1', 'p2', 'p3']) {
+        if (grouped[p].length === 0)
+            continue;
+        lines.push(`## ${p.toUpperCase()}`);
+        for (const a of grouped[p]) {
+            lines.push(`- [ ] **${a.category}** (${a.origin}) — ${a.targetArea}`);
+            lines.push(`      ${a.paraphrase ?? a.originalExcerpt.slice(0, 80)}…`);
+            if (a.recommendedCommands.length > 0) {
+                lines.push(`      next: ${a.recommendedCommands.join(' / ')}`);
+            }
+        }
+        lines.push('');
+    }
+    return {
+        schema: 'sharkcraft.feedback-backlog/v1',
+        generatedAt: new Date().toISOString(),
+        grouped,
+        markdown: lines.join('\n') + '\n',
+    };
+}
+export function buildFeedbackPromptReport(inspection, sourceFile) {
+    const actions = buildFeedbackActionsReport(inspection, sourceFile).actions;
+    const lines = ['# Implementation prompt', ''];
+    lines.push('The following sections were derived from real feedback. Implement them as separate parts; do not auto-apply.');
+    lines.push('');
+    for (const a of actions) {
+        lines.push(`## ${a.priority} ${a.targetArea} — ${a.category}`);
+        if (a.suggestedPromptSection)
+            lines.push(a.suggestedPromptSection);
+        lines.push('');
+        if (a.recommendedCommands.length > 0) {
+            lines.push('**Suggested commands:**');
+            for (const c of a.recommendedCommands)
+                lines.push(`- \`${c}\``);
+            lines.push('');
+        }
+    }
+    return {
+        schema: 'sharkcraft.feedback-prompt/v1',
+        generatedAt: new Date().toISOString(),
+        markdown: lines.join('\n') + '\n',
+    };
+}
+export function buildFeedbackPlanReport(inspection, sourceFile) {
+    const actions = buildFeedbackActionsReport(inspection, sourceFile).actions;
+    const ordered = [...actions].sort((a, b) => a.priority.localeCompare(b.priority));
+    return {
+        schema: 'sharkcraft.feedback-plan/v1',
+        generatedAt: new Date().toISOString(),
+        orderedActions: ordered,
+        validationGates: [
+            'shrk doctor',
+            'shrk self-config doctor',
+            'shrk check boundaries --changed-only',
+            'shrk safety audit --deep',
+        ],
+    };
+}

package/dist/feedback-ingestion.d.ts

@@ -0,0 +1,96 @@
+export declare const FEEDBACK_INGESTION_SCHEMA = "sharkcraft.feedback-ingestion/v1";
+export declare enum FeedbackBucket {
+    Good = "good",
+    Bad = "bad",
+    Missing = "missing",
+    PainPoint = "pain-point",
+    Other = "other"
+}
+export declare enum FeedbackSeverity {
+    Info = "info",
+    Minor = "minor",
+    Major = "major",
+    Blocker = "blocker"
+}
+export interface IFeedbackFinding {
+    bucket: FeedbackBucket;
+    text: string;
+    tags: ReadonlyArray<string>;
+    /** Best-guess target area (knowledge|templates|boundaries|trace|impact|doctor|...). */
+    targetArea?: string;
+    severity: FeedbackSeverity;
+    /** Suggested follow-up commands. */
+    suggestedCommands: ReadonlyArray<string>;
+}
+export interface IFeedbackReport {
+    schema: typeof FEEDBACK_INGESTION_SCHEMA;
+    sourceFile?: string;
+    generatedAt: string;
+    totalFindings: number;
+    counts: Record<FeedbackBucket, number>;
+    findings: ReadonlyArray<IFeedbackFinding>;
+    suggestedNextRound: ReadonlyArray<string>;
+}
+/**
+ * Public pack-extensible feedback rule. Schema:
+ * sharkcraft.feedback-rule/v1.
+ *
+ * Packs ship rules via `feedbackRuleFiles[]` in their manifest; the local
+ * project can also place `sharkcraft/feedback-rules.ts` with a default
+ * export of `IFeedbackRule[]`.
+ */
+export declare const FEEDBACK_RULE_SCHEMA = "sharkcraft.feedback-rule/v1";
+export interface IFeedbackRule {
+    id: string;
+    title: string;
+    description?: string;
+    /** Plain strings — matched case-insensitively as word fragments. */
+    keywords?: readonly string[];
+    /** Multi-word phrases. */
+    phrases?: readonly string[];
+    /** Raw regex strings (compiled with `i` flag). */
+    regexes?: readonly string[];
+    /** Bucket nudge — kept separate from bucket-derived severity. */
+    category?: 'good' | 'bad' | 'missing' | 'pain-point' | 'other';
+    /** Tag added to matching findings (besides rule.tags). */
+    tag?: string;
+    tags?: readonly string[];
+    /** Suggested target-area override. */
+    targetArea?: string;
+    severity?: FeedbackSeverity;
+    /** Concrete CLI commands to attach to matching findings. */
+    suggestedActions?: readonly string[];
+    /** Related ids (for downstream tooling). */
+    relatedCommands?: readonly string[];
+    relatedTemplates?: readonly string[];
+    relatedPlaybooks?: readonly string[];
+    relatedKnowledge?: readonly string[];
+    /** When this rule should apply — informational; not enforced today. */
+    appliesWhen?: readonly string[];
+}
+export declare function defineFeedbackRule<T extends IFeedbackRule>(r: T): T;
+export interface IIngestFeedbackOptions {
+    /** Additional pack/local feedback rules to apply on top of built-ins. */
+    rules?: readonly IFeedbackRule[];
+}
+export declare function ingestFeedbackText(text: string, sourceFile?: string, options?: IIngestFeedbackOptions): IFeedbackReport;
+export declare function ingestFeedbackFile(projectRoot: string, file: string, options?: IIngestFeedbackOptions): IFeedbackReport;
+/**
+ * Load pack + local feedback rules. Local file:
+ * `sharkcraft/feedback-rules.ts` exporting an `IFeedbackRule[]` default.
+ * Packs contribute via `feedbackRuleFiles[]` in their manifest.
+ */
+export declare function loadFeedbackRules(inspection: {
+    projectRoot: string;
+    sharkcraftDir: string | null;
+    packs?: {
+        validPacks?: readonly {
+            packageRoot: string;
+            manifest?: {
+                contributions?: unknown;
+            } | null;
+        }[];
+    };
+}): Promise<readonly IFeedbackRule[]>;
+export declare function renderFeedbackBacklog(report: IFeedbackReport): string;
+//# sourceMappingURL=feedback-ingestion.d.ts.map

package/dist/feedback-ingestion.d.ts.map

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

package/dist/feedback-ingestion.js

@@ -0,0 +1,400 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Feedback ingestion.
+ *
+ * Parses freeform markdown/text feedback into structured findings the
+ * agent (or a human) can convert into a backlog. Deterministic, no AI.
+ *
+ * Heuristics:
+ *  - Section headings (`# Good`, `## Bad`, `### Missing`, etc.) seed
+ *    initial bucket.
+ *  - Bullet markers (`-`, `*`, `+`, numbered) become findings.
+ *  - Keyword scan over each bullet adds tags and likely-target-area.
+ *
+ * Schema: sharkcraft.feedback-ingestion/v1
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import * as nodePath from 'node:path';
+export const FEEDBACK_INGESTION_SCHEMA = 'sharkcraft.feedback-ingestion/v1';
+export var FeedbackBucket;
+(function (FeedbackBucket) {
+    FeedbackBucket["Good"] = "good";
+    FeedbackBucket["Bad"] = "bad";
+    FeedbackBucket["Missing"] = "missing";
+    FeedbackBucket["PainPoint"] = "pain-point";
+    FeedbackBucket["Other"] = "other";
+})(FeedbackBucket || (FeedbackBucket = {}));
+export var FeedbackSeverity;
+(function (FeedbackSeverity) {
+    FeedbackSeverity["Info"] = "info";
+    FeedbackSeverity["Minor"] = "minor";
+    FeedbackSeverity["Major"] = "major";
+    FeedbackSeverity["Blocker"] = "blocker";
+})(FeedbackSeverity || (FeedbackSeverity = {}));
+/**
+ * Public pack-extensible feedback rule. Schema:
+ * sharkcraft.feedback-rule/v1.
+ *
+ * Packs ship rules via `feedbackRuleFiles[]` in their manifest; the local
+ * project can also place `sharkcraft/feedback-rules.ts` with a default
+ * export of `IFeedbackRule[]`.
+ */
+export const FEEDBACK_RULE_SCHEMA = 'sharkcraft.feedback-rule/v1';
+export function defineFeedbackRule(r) {
+    return r;
+}
+function compileExternalRule(r) {
+    const fragments = [];
+    for (const kw of r.keywords ?? []) {
+        if (kw.trim().length === 0)
+            continue;
+        fragments.push(`\\b${escapeRegex(kw)}\\b`);
+    }
+    for (const ph of r.phrases ?? []) {
+        if (ph.trim().length === 0)
+            continue;
+        fragments.push(escapeRegex(ph));
+    }
+    for (const raw of r.regexes ?? []) {
+        if (raw.trim().length === 0)
+            continue;
+        fragments.push(`(?:${raw})`);
+    }
+    if (fragments.length === 0)
+        return null;
+    let pattern;
+    try {
+        pattern = new RegExp(fragments.join('|'), 'i');
+    }
+    catch {
+        return null;
+    }
+    const tags = new Set();
+    if (r.tag)
+        tags.add(r.tag);
+    for (const t of r.tags ?? [])
+        tags.add(t);
+    const out = {
+        pattern,
+        tags: [...tags],
+        targetArea: r.targetArea ?? r.id,
+        suggestedCommands: [...(r.suggestedActions ?? []), ...(r.relatedCommands ?? [])],
+    };
+    if (r.severity)
+        out.severity = r.severity;
+    return out;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+const KEYWORD_RULES = [
+    {
+        pattern: /\b(changed-only|changed only)\b/i,
+        tags: ['changed-only'],
+        targetArea: 'boundaries-changed-only',
+        suggestedCommands: ['shrk check boundaries --changed-only', 'shrk policy run --changed-only'],
+    },
+    {
+        pattern: /\b(boundary|boundaries)\b/i,
+        tags: ['boundary'],
+        targetArea: 'boundaries',
+        suggestedCommands: ['shrk check boundaries'],
+    },
+    {
+        pattern: /\b(stale|rot|outdated|drift)\b/i,
+        tags: ['stale'],
+        targetArea: 'knowledge-integrity',
+        suggestedCommands: ['shrk knowledge stale-check', 'shrk templates drift'],
+    },
+    {
+        pattern: /\b(template[s]?)\b/i,
+        tags: ['templates'],
+        targetArea: 'templates',
+        suggestedCommands: ['shrk templates list', 'shrk templates drift'],
+    },
+    {
+        pattern: /\b(playbook[s]?)\b/i,
+        tags: ['playbooks'],
+        targetArea: 'playbooks',
+        suggestedCommands: ['shrk playbooks list'],
+    },
+    {
+        pattern: /\b(warning|noisy|noise)\b/i,
+        tags: ['noise'],
+        targetArea: 'doctor-suppressions',
+        suggestedCommands: ['shrk doctor --quiet-known', 'shrk doctor suppressions list'],
+        severity: FeedbackSeverity.Minor,
+    },
+    {
+        pattern: /\b(rename|move|moved|renamed)\b/i,
+        tags: ['rename'],
+        targetArea: 'knowledge-rename',
+        suggestedCommands: ['shrk knowledge rename-symbol <old> <new> --dry-run'],
+    },
+    {
+        pattern: /\b(trace|impact)\b/i,
+        tags: ['trace-impact'],
+        targetArea: 'trace-impact',
+        suggestedCommands: ['shrk trace <query>', 'shrk impact <file>'],
+    },
+    {
+        pattern: /\b(mcp|tool[s]?)\b/i,
+        tags: ['mcp'],
+        targetArea: 'mcp',
+        suggestedCommands: ['shrk commands list --filter mcp'],
+    },
+    {
+        pattern: /\b(plugin)\b/i,
+        tags: ['plugin'],
+        targetArea: 'plugin-lifecycle',
+        suggestedCommands: ['shrk plugin lifecycle list', 'shrk plugin rename <old> <new>'],
+    },
+    {
+        pattern: /\b(helper[s]?)\b/i,
+        tags: ['helpers'],
+        targetArea: 'helpers',
+        suggestedCommands: ['shrk helper list'],
+    },
+    {
+        pattern: /\b(registry|register|remove)\b/i,
+        tags: ['registry-lifecycle'],
+        targetArea: 'registry-lifecycle',
+        suggestedCommands: ['shrk check registry-lifecycle'],
+    },
+    {
+        pattern: /\b(slow|hang|crash|broken|fail|stuck)\b/i,
+        tags: ['bug'],
+        targetArea: 'bug',
+        severity: FeedbackSeverity.Major,
+    },
+    {
+        pattern: /\b(documentation|docs)\b/i,
+        tags: ['docs'],
+        targetArea: 'docs',
+        suggestedCommands: ['shrk docs check'],
+    },
+];
+function findHeadingBucket(line) {
+    const m = /^#{1,6}\s+(.*?)\s*$/.exec(line);
+    if (!m)
+        return null;
+    const text = m[1].toLowerCase();
+    if (/\b(good|win|works|liked|positive)\b/.test(text))
+        return FeedbackBucket.Good;
+    if (/\b(bad|missing|gaps?|broken|negative|pain|issue|problem|frustration)\b/.test(text)) {
+        if (/\bmissing\b/.test(text))
+            return FeedbackBucket.Missing;
+        if (/\bpain\b/.test(text))
+            return FeedbackBucket.PainPoint;
+        return FeedbackBucket.Bad;
+    }
+    if (/\b(neutral|info|note)\b/.test(text))
+        return FeedbackBucket.Other;
+    return null;
+}
+function isBulletLine(line) {
+    return /^\s*[-*+]\s+/.test(line) || /^\s*\d+\.\s+/.test(line);
+}
+function stripBullet(line) {
+    return line.replace(/^\s*[-*+]\s+/, '').replace(/^\s*\d+\.\s+/, '').trim();
+}
+function applyKeywordRules(text, customRules = []) {
+    const tags = new Set();
+    const suggested = new Set();
+    let target;
+    let severityHint = FeedbackSeverity.Info;
+    const allRules = [...KEYWORD_RULES, ...customRules];
+    for (const rule of allRules) {
+        if (rule.pattern.test(text)) {
+            for (const t of rule.tags)
+                tags.add(t);
+            if (!target)
+                target = rule.targetArea;
+            for (const c of rule.suggestedCommands ?? [])
+                suggested.add(c);
+            if (rule.severity && severityRank(rule.severity) > severityRank(severityHint)) {
+                severityHint = rule.severity;
+            }
+        }
+    }
+    return {
+        tags: [...tags],
+        targetArea: target,
+        suggested: [...suggested],
+        severityHint,
+    };
+}
+function severityRank(s) {
+    switch (s) {
+        case FeedbackSeverity.Info:
+            return 1;
+        case FeedbackSeverity.Minor:
+            return 2;
+        case FeedbackSeverity.Major:
+            return 3;
+        case FeedbackSeverity.Blocker:
+            return 4;
+    }
+}
+function refineSeverity(bucket, hint) {
+    if (bucket === FeedbackBucket.Good)
+        return FeedbackSeverity.Info;
+    if (bucket === FeedbackBucket.PainPoint || bucket === FeedbackBucket.Bad) {
+        return severityRank(hint) < severityRank(FeedbackSeverity.Minor) ? FeedbackSeverity.Minor : hint;
+    }
+    return hint;
+}
+export function ingestFeedbackText(text, sourceFile, options = {}) {
+    const customRules = [];
+    for (const r of options.rules ?? []) {
+        const compiled = compileExternalRule(r);
+        if (compiled)
+            customRules.push(compiled);
+    }
+    let bucket = FeedbackBucket.Other;
+    const findings = [];
+    for (const rawLine of text.split('\n')) {
+        const headingBucket = findHeadingBucket(rawLine);
+        if (headingBucket) {
+            bucket = headingBucket;
+            continue;
+        }
+        if (!isBulletLine(rawLine))
+            continue;
+        const stripped = stripBullet(rawLine);
+        if (!stripped)
+            continue;
+        const { tags, targetArea, suggested, severityHint } = applyKeywordRules(stripped, customRules);
+        const severity = refineSeverity(bucket, severityHint);
+        const finding = {
+            bucket,
+            text: stripped,
+            tags,
+            severity,
+            suggestedCommands: suggested,
+            ...(targetArea ? { targetArea } : {}),
+        };
+        findings.push(finding);
+    }
+    const counts = {
+        [FeedbackBucket.Good]: 0,
+        [FeedbackBucket.Bad]: 0,
+        [FeedbackBucket.Missing]: 0,
+        [FeedbackBucket.PainPoint]: 0,
+        [FeedbackBucket.Other]: 0,
+    };
+    for (const f of findings)
+        counts[f.bucket] += 1;
+    const targets = new Set();
+    for (const f of findings)
+        if (f.targetArea)
+            targets.add(f.targetArea);
+    const suggestedNextRound = [...targets].slice(0, 8).map((t) => `Improve ${t}`);
+    return {
+        schema: FEEDBACK_INGESTION_SCHEMA,
+        ...(sourceFile ? { sourceFile } : {}),
+        generatedAt: new Date().toISOString(),
+        totalFindings: findings.length,
+        counts,
+        findings,
+        suggestedNextRound,
+    };
+}
+export function ingestFeedbackFile(projectRoot, file, options = {}) {
+    const abs = nodePath.isAbsolute(file) ? file : nodePath.join(projectRoot, file);
+    const text = readFileSync(abs, 'utf8');
+    return ingestFeedbackText(text, file, options);
+}
+/**
+ * Load pack + local feedback rules. Local file:
+ * `sharkcraft/feedback-rules.ts` exporting an `IFeedbackRule[]` default.
+ * Packs contribute via `feedbackRuleFiles[]` in their manifest.
+ */
+export async function loadFeedbackRules(inspection) {
+    const out = [];
+    const seen = new Set();
+    const add = (r) => {
+        if (!r?.id || seen.has(r.id))
+            return;
+        seen.add(r.id);
+        out.push(r);
+    };
+    // Local file.
+    if (inspection.sharkcraftDir) {
+        const local = nodePath.join(inspection.sharkcraftDir, 'feedback-rules.ts');
+        for (const r of await importDefaultArray(local))
+            add(r);
+    }
+    // Pack contributions.
+    const packs = inspection.packs?.validPacks ?? [];
+    for (const pack of packs) {
+        const c = (pack.manifest?.contributions ?? {});
+        for (const rel of c.feedbackRuleFiles ?? []) {
+            const full = nodePath.resolve(pack.packageRoot, rel);
+            for (const r of await importDefaultArray(full))
+                add(r);
+        }
+    }
+    return out;
+}
+async function importDefaultArray(absPath) {
+    try {
+        if (!existsSync(absPath))
+            return [];
+        const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(absPath).href)));
+        return Array.isArray(mod.default) ? mod.default : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function renderFeedbackBacklog(report) {
+    const lines = [];
+    lines.push('# Feedback backlog');
+    lines.push('');
+    lines.push(`Generated: ${report.generatedAt}`);
+    if (report.sourceFile)
+        lines.push(`Source: ${report.sourceFile}`);
+    lines.push('');
+    const bucketOrder = [
+        FeedbackBucket.PainPoint,
+        FeedbackBucket.Missing,
+        FeedbackBucket.Bad,
+        FeedbackBucket.Other,
+        FeedbackBucket.Good,
+    ];
+    for (const b of bucketOrder) {
+        const rows = report.findings.filter((f) => f.bucket === b);
+        if (rows.length === 0)
+            continue;
+        lines.push(`## ${b}`);
+        lines.push('');
+        for (const r of rows) {
+            lines.push(`- [${r.severity}] ${r.text}`);
+            if (r.targetArea)
+                lines.push(`  - target: ${r.targetArea}`);
+            if (r.tags.length > 0)
+                lines.push(`  - tags: ${r.tags.join(', ')}`);
+            if (r.suggestedCommands.length > 0) {
+                lines.push('  - commands:');
+                for (const c of r.suggestedCommands)
+                    lines.push(`    - \`${c}\``);
+            }
+        }
+        lines.push('');
+    }
+    if (report.suggestedNextRound.length > 0) {
+        lines.push('## Suggested next round');
+        for (const r of report.suggestedNextRound)
+            lines.push(`- ${r}`);
+    }
+    return lines.join('\n') + '\n';
+}