c64-kb 0.17.0

package/dist/tools/briefings/build.js

@@ -0,0 +1,185 @@
+/**
+ * The briefing pipeline: resolve the archetype, propose techniques, look
+ * each up, then check compatibility, gather pitfalls, split toolchains,
+ * order the build, add up the budget and render.
+ */
+import { techniqueLookup, checkCompatibility } from "../query.js";
+import { getAnalytics } from "../../context.js";
+import { BriefingSchema, } from "../../schemas/tool-outputs.js";
+import { resolveArchetype, routeArchetypeFromBrief, seedsFor, } from "./archetype.js";
+import { contradictsBriefAxis, resolveProposedTechniques } from "./discovery.js";
+import { whyProposed } from "./why-proposed.js";
+import { collectPitfalls } from "./plan-pitfalls.js";
+import { toolchainSplit } from "./toolchain.js";
+import { buildOrder } from "./build-order.js";
+import { computeBudget } from "./budget.js";
+import { fetchBudgetMembers } from "../query/plan-budget.js";
+import { designsOfArchetype } from "../query/game-design.js";
+import { briefSummary, renderBriefingText } from "./render.js";
+const ComplexitySchema = BriefingSchema.shape.proposed_techniques.element.shape.complexity;
+const RegionSchema = BriefingSchema.shape.proposed_techniques.element.shape.region;
+const MAX_PER_CATEGORY = 3;
+/** A long, specific brief names more parts than a short one. Ten slots made a nine-part platformer brief drop its LFSR. */
+function proposalLimitFor(description) {
+    const briefWords = description.split(/\s+/).filter(Boolean).length;
+    if (briefWords >= 40)
+        return 16;
+    if (briefWords >= 20)
+        return 13;
+    return 10;
+}
+/**
+ * Drop techniques the lookup did not find (empty name), cap at three per
+ * category (P5-6), then cap the non-forced total at the proposal limit.
+ * Archetype FEATURES pass both caps.
+ */
+function selectTechniques(enriched, archetypeForced, proposalLimit) {
+    const categoryCounts = new Map();
+    let nonForced = 0;
+    return enriched.filter((t) => {
+        if (t.name === "")
+            return false;
+        if (archetypeForced.has(t.name))
+            return true;
+        const cat = t.category || "_uncategorized";
+        const count = categoryCounts.get(cat) ?? 0;
+        if (count >= MAX_PER_CATEGORY || nonForced >= proposalLimit)
+            return false;
+        categoryCounts.set(cat, count + 1);
+        nonForced++;
+        return true;
+    });
+}
+/** The reason a technique is in the plan: the archetype's fingerprint when it forced it, else the brief. */
+function reasonFor(t, description, resolved) {
+    if (resolved?.mode === "graph" && resolved.features.includes(t.name)) {
+        return `In the ${resolved.archetype.name} archetype's technique fingerprint`;
+    }
+    return whyProposed(t.name, t.category, description);
+}
+function proposedOf(t, description, resolved) {
+    // An empty or unknown complexity or region word is left out, as the
+    // output schema allows only its enum values.
+    const complexity = ComplexitySchema.safeParse(t.complexity || undefined);
+    const region = RegionSchema.safeParse(t.requires_region);
+    return {
+        name: t.name,
+        title: t.title,
+        category: t.category,
+        complexity: complexity.success ? complexity.data : undefined,
+        why_proposed: reasonFor(t, description, resolved),
+        uses_registers: t.uses_registers.map((r) => r.name),
+        uses_kernal: t.uses_kernal.map((k) => k.name),
+        region: region.success ? region.data : undefined,
+        implementing_recipes: t.recipes.map((r) => r.name),
+    };
+}
+async function compatibilityOf(techs) {
+    if (techs.length < 2) {
+        return {
+            verdict: "compatible",
+            compatibility: { conflicts: [], warnings: [], shared_infrastructure: [] },
+        };
+    }
+    const { structured } = await checkCompatibility(techs.map((t) => t.name));
+    const compatibility = {
+        conflicts: structured.conflicts.filter((c) => c.kind === "region_mismatch"),
+        warnings: structured.conflicts.filter((c) => c.kind === "shared_register" || c.kind === "shared_kernal"),
+        shared_infrastructure: structured.shared_infrastructure,
+    };
+    return { verdict: structured.verdict, compatibility };
+}
+async function proposeTechniques(description, archetype, resolved, isGame) {
+    const seeds = seedsFor({ description, archetype, resolved, isGame });
+    const proposalLimit = proposalLimitFor(description);
+    const techNames = await resolveProposedTechniques(seeds.searchDescription, proposalLimit, seeds.archetypeForced.size);
+    // Prepend forced techniques so they survive the per-category MAX cap.
+    for (const name of seeds.forced.slice().reverse()) {
+        if (!techNames.includes(name))
+            techNames.unshift(name);
+    }
+    const enriched = await Promise.all(techNames.map(async (name) => (await techniqueLookup(name)).structured));
+    // A forced technique stays whatever its axis; a found one on the axis the
+    // brief did not ask for goes.
+    const onAxis = enriched.filter((t) => seeds.forced.includes(t.name) || !contradictsBriefAxis(t, seeds.searchDescription));
+    return selectTechniques(onAxis, seeds.archetypeForced, proposalLimit);
+}
+function archetypeFields(resolved) {
+    if (resolved?.mode === "graph") {
+        return {
+            archetype: {
+                ...resolved.archetype,
+                features: resolved.features,
+                risks: resolved.risks,
+                ...(resolved.resolved_from ? { resolved_from: resolved.resolved_from } : {}),
+                ...(resolved.inferred_from ? { inferred_from: resolved.inferred_from } : {}),
+            },
+        };
+    }
+    if (resolved?.mode === "not_found") {
+        return {
+            archetype_not_found: {
+                requested: resolved.requested,
+                known: resolved.known,
+                ...(resolved.candidates ? { candidates: resolved.candidates } : {}),
+            },
+        };
+    }
+    return {};
+}
+/** The GameDesigns of a resolved archetype; absent when there are none. */
+async function designFields(resolved) {
+    if (resolved?.mode !== "graph")
+        return {};
+    const designs = await designsOfArchetype(resolved.archetype.name);
+    if (designs.length === 0)
+        return {};
+    return {
+        designs: designs.map((d) => ({
+            name: d.name,
+            title: d.title,
+            realised_by: d.realised_by,
+            composes: d.composes,
+            measured: d.measured.map((m) => ({ ...m, typical: m.typical ?? null })),
+        })),
+    };
+}
+/**
+ * A named archetype is looked up. A game brief that names none is routed by
+ * the archetypes' brief words; a demo brief that names none is not.
+ */
+async function resolutionFor(description, archetype, isGame) {
+    if (archetype !== undefined)
+        return resolveArchetype(archetype, isGame ? "game" : "demo");
+    return isGame ? routeArchetypeFromBrief(description) : undefined;
+}
+export async function buildBriefing(description, archetype, isGame) {
+    const resolved = await resolutionFor(description, archetype, isGame);
+    const techs = await proposeTechniques(description, archetype, resolved, isGame);
+    const techNames = techs.map((t) => t.name);
+    const proposed_techniques = techs.map((t) => proposedOf(t, description, resolved));
+    const { verdict, compatibility } = await compatibilityOf(techs);
+    const pitfalls = await collectPitfalls(techNames, resolved?.mode === "graph" ? resolved.risks : []);
+    const toolchain_split = await toolchainSplit(techs);
+    const { build_order, scaffoldPages } = await buildOrder({ techs, isGame, resolved, archetype });
+    const budget = computeBudget(await fetchBudgetMembers(techNames.map((name) => ({ name, phase: "play" }))));
+    const plan = { proposed_techniques, pitfalls, toolchain_split, budget };
+    const structured = {
+        brief: briefSummary({ description, isGame, resolved, archetype, plan, verdict }),
+        proposed_techniques,
+        compatibility,
+        pitfalls,
+        toolchain_split,
+        build_order,
+        budget,
+        ...archetypeFields(resolved),
+        ...(await designFields(resolved)),
+    };
+    getAnalytics().logQuery({
+        tool: isGame ? "c64_game_briefing" : "c64_demo_briefing",
+        query: description,
+        resultCount: techs.length,
+    });
+    return { structured, text: renderBriefingText(structured, isGame, scaffoldPages) };
+}
+//# sourceMappingURL=build.js.map

package/dist/tools/briefings/build.js.map

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

package/dist/tools/briefings/discovery.js

@@ -0,0 +1,290 @@
+/**
+ * Technique discovery for a briefing: keyword scoring against the graph
+ * (primary) merged with vector search (supplementary).
+ */
+import { search } from "../query.js";
+import { getFalkor } from "../../context.js";
+import { parseRows, TechniqueScoreRow } from "./rows.js";
+/**
+ * Given a Qdrant chunk section string like
+ *   "Raster Techniques > stable_raster_irq — Stable raster IRQ"
+ *   "Logic Techniques > vehicle_control — Top-down driving ... > How"
+ * extract the snake_case technique name ("stable_raster_irq").
+ *
+ * The name is in the H2 segment. That is the last segment only for text
+ * directly under the H2; an H3 chunk ends in its own heading ("How",
+ * "Recipes"). Until 2026-09-23 only the last segment was read, so no H3
+ * chunk, which is most of a modern technique page, contributed a name: a
+ * road-shooter brief whose best vector hits were vehicle_control's H3s
+ * got none of them.
+ *
+ * Coupling: this reads the chunker's output format (src/services/chunker.ts
+ * joins `{H1} > {H2} > {H3}`), not a field of the payload. The technique-doc
+ * H2 format is `## snake_name — Title`. If either changes, vector hits stop
+ * contributing technique names here and briefings silently fall back to
+ * keyword scoring alone. A technique-name field on the chunk payload would
+ * remove this parse.
+ */
+export function extractTechniqueNameFromSection(section) {
+    for (const segment of section.split(" > ")) {
+        const dashIdx = segment.indexOf(" — ");
+        if (dashIdx === -1)
+            continue;
+        const candidate = segment.slice(0, dashIdx).trim();
+        // Must be lowercase with underscores only (technique snake_case)
+        if (/^[a-z][a-z0-9_]*$/.test(candidate))
+            return candidate;
+    }
+    return null;
+}
+// Scene-tier signal words: when the brief explicitly mentions one of these,
+// don't penalize high / scene-tier techniques (the user wants the exotic stuff).
+const SCENE_TIER_KEYWORDS = [
+    "sideborder",
+    "open border",
+    "open the border",
+    "fli",
+    "vsp",
+    "dycp",
+    "interlace",
+    "twister",
+    "rotozoom",
+    "8580 vs",
+    "6581 vs",
+    "cycle-exact",
+    "cycle exact",
+    "scene tier",
+    "advanced effect",
+];
+// Per-complexity penalty applied unless scene-tier signals appear.
+// Reason: hybrid search ranks rare/scene-tier techniques higher (fewer chunks
+// = less score dilution), so foundations like stable_raster_irq lose to
+// exotic siblings like topbottom_border_open. The penalty rebalances.
+const COMPLEXITY_PENALTY_NORMAL = {
+    low: 0,
+    medium: 0,
+    high: 1.0,
+    "scene-tier": 2.0,
+};
+const COMPLEXITY_PENALTY_NONE = { low: 0, medium: 0, high: 0, "scene-tier": 0 };
+// Words that say nothing about a technique. "and" matched the name words of
+// drive_code_upload_and_job_queue, compare_16bit_and_signed and
+// text_window_and_menu, so every brief with an "and" in it proposed them;
+// "game" matched sprite_multiplex_game in every game brief; "through" put
+// colour_fade, dycp_scroller and hires_plot into a Boulder Dash plan.
+const STOP_WORDS = new Set([
+    "and",
+    "the",
+    "with",
+    "without",
+    "for",
+    "from",
+    "into",
+    "onto",
+    "through",
+    "like",
+    "style",
+    "game",
+    "games",
+    "that",
+    "this",
+    "its",
+    "their",
+    "them",
+    "then",
+    "than",
+    "when",
+    "where",
+    "which",
+    "while",
+    "via",
+    "per",
+    "any",
+    "all",
+    "each",
+    "every",
+    "some",
+    "many",
+    "more",
+    "most",
+    "are",
+    "has",
+]);
+// Acronyms that are also English words. In lower case the brief means the
+// word: "enemy cars ram" put screen_ram_relocation, charset_copy_rom_to_ram
+// and char_scroll_buffer_h ("screen-RAM") into a road-shooter plan. In
+// capitals ("RAM") it means the acronym.
+const ACRONYM_HOMOGRAPHS = new Set(["ram"]);
+/** A raw word the brief means as the English word, not the acronym. */
+function isLowerCaseHomograph(raw) {
+    return ACRONYM_HOMOGRAPHS.has(raw.toLowerCase()) && raw !== raw.toUpperCase();
+}
+/** Tokenize and add stemmed variants (strip common suffixes like -ing, -er, -ers). */
+export function briefTokens(description) {
+    const rawTokens = description
+        .split(/[\s_,:;!?+\-()]+/)
+        .filter((t) => !isLowerCaseHomograph(t))
+        .map((t) => t.toLowerCase())
+        .filter((t) => t.length >= 3 && !STOP_WORDS.has(t));
+    return Array.from(new Set([
+        ...rawTokens,
+        ...rawTokens.map((t) => (t.endsWith("ing") && t.length > 5 ? t.slice(0, -3) : t)),
+        ...rawTokens.map((t) => (t.endsWith("ers") && t.length > 5 ? t.slice(0, -3) : t)),
+        ...rawTokens.map((t) => (t.endsWith("er") && t.length > 5 ? t.slice(0, -2) : t)),
+        ...rawTokens.map((t) => (t.endsWith("s") && t.length > 4 ? t.slice(0, -1) : t)),
+    ])).filter((t) => t.length >= 3);
+}
+const AXIS_WORDS = { vertical: ["vertical", "vertically"], horizontal: ["horizontal", "horizontally"] };
+/**
+ * True when a technique scrolls along the axis the brief did not ask for:
+ * the brief names one axis and not the other, and the technique, or one it
+ * requires, has a name ending in the other axis letter (`_h`, `_v`) or a
+ * title naming the other axis. "scroll" alone is a whole-word hit on every
+ * scroll technique, so a vertically scrolling road shooter was proposed
+ * char_scroll_buffer_h, soft_scroll_h and charset_parallax (which requires
+ * infinite_scroll_h).
+ */
+export function contradictsBriefAxis(tech, description) {
+    const words = new Set(description.toLowerCase().split(/[^a-z]+/));
+    const saysV = AXIS_WORDS.vertical.some((w) => words.has(w));
+    const saysH = AXIS_WORDS.horizontal.some((w) => words.has(w));
+    if (saysV === saysH)
+        return false;
+    const [letter, other] = saysV ? ["h", AXIS_WORDS.horizontal] : ["v", AXIS_WORDS.vertical];
+    return [tech, ...(tech.requires ?? [])].some((t) => {
+        const titleWords = new Set((t.title ?? "").toLowerCase().split(/[^a-z]+/));
+        return t.name.endsWith(`_${letter}`) || other.some((w) => titleWords.has(w));
+    });
+}
+function recipeBonusFor(recipeCount) {
+    if (recipeCount >= 2)
+        return 1.5;
+    if (recipeCount >= 1)
+        return 0.75;
+    return 0;
+}
+function scoreTechnique(r, tokens, complexityPenalty) {
+    const name = r.name.toLowerCase();
+    const title = (r.title ?? "").toLowerCase();
+    const category = (r.category ?? "").toLowerCase();
+    const complexity = (r.complexity ?? "medium").toLowerCase();
+    // Whole words only. Substring matching let "budget bar" propose
+    // raster_bars and "tile map" reach every bitmap technique through the
+    // category word, so a long brief filled its slots with misses
+    // (three-arm build test, 2026-09-22).
+    const nameWords = new Set(name.split("_").filter(Boolean));
+    const words = new Set([
+        ...nameWords,
+        ...title.split(/[^a-z0-9$.]+/).filter((w) => w.length >= 3),
+        category,
+    ]);
+    const hits = tokens.filter((t) => words.has(t)).length;
+    // Bonus: if a token is the technique's category word
+    const categoryBonus = tokens.some((t) => category === t) ? 0.5 : 0;
+    // Bonus: if a token is one of the words of the snake_case name (strong match)
+    const nameBonus = tokens.some((t) => nameWords.has(t)) ? 0.5 : 0;
+    // Recipe-evidence bonus: techniques with implementing recipes are more
+    // idiomatic and should outrank exotic siblings with no worked example.
+    const recipeBonus = recipeBonusFor(Number(r.recipe_count ?? 0));
+    // Complexity penalty: rebalance against vector-search's rare-page bias.
+    const penalty = complexityPenalty[complexity] ?? 0;
+    return { name: r.name, hits, score: hits + categoryBonus + nameBonus + recipeBonus - penalty };
+}
+/**
+ * Query FalkorDB for all techniques and score them by keyword overlap
+ * with the description PLUS implementation-evidence (recipe count) and
+ * complexity. This is the primary technique-discovery source.
+ *
+ * Scoring (sum):
+ *   - hits          : token overlap with name/title/category
+ *   - categoryBonus : +0.5 if a token equals the category
+ *   - nameBonus     : +0.5 if a token is a word of the snake_case name
+ *   - recipeBonus   : +1.5 if 2+ recipes implement; +0.75 if exactly 1
+ *   - complexityPen : -1.0 (high), -2.0 (scene-tier) unless the brief
+ *                     explicitly asks for scene-tier work
+ *
+ * The recipe bonus encodes "this technique is idiomatic enough that the KB
+ * has multiple worked examples for it"; the complexity penalty counters the
+ * vector-search bias toward rare-but-dense exotic technique pages.
+ */
+async function findTechniquesByKeyword(description, keep = 12) {
+    const f = await getFalkor();
+    const result = await f.roQuery(`MATCH (t:Technique)
+     OPTIONAL MATCH (r:Recipe)-[:IMPLEMENTS]->(t)
+     RETURN t.name AS name, t.title AS title, t.category AS category,
+            t.complexity AS complexity, count(r) AS recipe_count`);
+    const tokens = briefTokens(description);
+    const descLower = description.toLowerCase();
+    const wantsSceneTier = SCENE_TIER_KEYWORDS.some((k) => descLower.includes(k));
+    const complexityPenalty = wantsSceneTier ? COMPLEXITY_PENALTY_NONE : COMPLEXITY_PENALTY_NORMAL;
+    return (parseRows(TechniqueScoreRow, result.data)
+        .map((row) => scoreTechnique(row, tokens, complexityPenalty))
+        // A technique must share a word with the brief. The recipe bonus is
+        // positive on its own, so until 2026-09-23 every technique with a
+        // recipe and no matching word scored 0.75 or 1.5 and filled a short
+        // brief's empty slots in alphabetical order (char_rom_under_vic,
+        // compare_16bit_and_signed, cpu_io_port_bank, decimal_print, ...).
+        .filter((s) => s.hits > 0 && s.score > 0)
+        // Score descending; alphabetical tiebreak so equal-score ranks are
+        // stable across runs (Array.sort is now stable in V8 but the input
+        // order from the graph query is not guaranteed).
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+        .slice(0, keep) // keyword candidates; merging takes what it needs
+        .map((s) => s.name));
+}
+/**
+ * Resolve technique names from keyword scoring (primary) + vector search
+ * (supplementary). Returns up to `limit` + 8 unique technique names ordered
+ * by relevance.
+ *
+ * Strategy: keyword scoring includes recipe-count and complexity signals
+ * (see findTechniquesByKeyword), so it picks idiomatic foundations over
+ * exotic siblings — exactly the bias we want. Vector search fills in
+ * semantically-related techniques the keyword scorer might miss.
+ *
+ * Prior to 2026-05-18 the order was reversed (vector-first, keyword-fills),
+ * which produced briefings dominated by rare/scene-tier techniques because
+ * vector similarity scores higher for rare technique pages.
+ */
+export async function resolveProposedTechniques(description, limit = 8, 
+/** Techniques the caller already forces (an archetype's fingerprint); they count as found. */
+forcedCount = 0) {
+    // Run both sources in parallel for speed
+    const [searchResult, fromKeyword] = await Promise.all([
+        search(description, 20),
+        findTechniquesByKeyword(description, Math.max(12, limit)),
+    ]);
+    // 1. Collect technique names from vector search (technique-doc chunks only)
+    const fromSearch = [];
+    for (const hit of searchResult.structured.hits) {
+        if (!hit.source.startsWith("techniques/"))
+            continue;
+        const name = extractTechniqueNameFromSection(hit.section);
+        if (name && !fromSearch.includes(name))
+            fromSearch.push(name);
+    }
+    // 2. Merge: keyword names first (recipe + complexity weighted), then
+    // vector names that aren't already included as a semantic supplement.
+    // When the brief's own words already found most of the plan, the vector
+    // side adds at most four: on a long brief it was filling the remaining
+    // slots with guesses (a colour fade and a scroll buffer for a platformer
+    // that named neither). A vague brief still gets the full supplement. An
+    // archetype's forced fingerprint counts as found: a short brief routed to
+    // an archetype is not vague.
+    const merged = [...fromKeyword];
+    const supplementCap = fromKeyword.length + forcedCount >= 6 ? 4 : Infinity;
+    let supplemented = 0;
+    for (const name of fromSearch) {
+        if (merged.length >= limit || supplemented >= supplementCap)
+            break;
+        if (!merged.includes(name)) {
+            merged.push(name);
+            supplemented++;
+        }
+    }
+    // Hand back a few more than the limit: the caller caps per category, and
+    // a slice taken here before that cap let sixteen raster and sprite hits
+    // crowd out the brief's one maths noun.
+    return merged.slice(0, limit + 8);
+}
+//# sourceMappingURL=discovery.js.map

package/dist/tools/briefings/discovery.js.map

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

package/dist/tools/briefings/plan-pitfalls.js

@@ -0,0 +1,69 @@
+/**
+ * The briefing's pitfall list: each proposed technique's pitfalls, then the
+ * archetype's RISKS, de-duplicated and ordered by severity.
+ */
+import { pitfallsFor } from "../pitfalls.js";
+import { getFalkor } from "../../context.js";
+import { parseRows, presentNames, RiskPitfallRow } from "./rows.js";
+const SEVERITY_ORDER = new Map([
+    ["critical", 0],
+    ["high", 1],
+    ["medium", 2],
+    ["low", 3],
+]);
+async function perTechniquePitfalls(techNames, seen) {
+    const proposed = new Set(techNames);
+    const perTech = await Promise.all(techNames.map(async (techName) => ({ techName, result: await pitfallsFor(techName) })));
+    const out = [];
+    for (const { techName, result } of perTech) {
+        for (const p of result.structured.pitfalls) {
+            if (seen.has(p.name))
+                continue;
+            seen.add(p.name);
+            // Which of the proposed techniques triggered this pitfall?
+            const triggeredByProposed = p.triggered_by.filter((tb) => proposed.has(tb.name)).map((tb) => tb.name);
+            out.push({
+                name: p.name,
+                title: p.title,
+                severity: p.severity,
+                triggered_by_proposed: triggeredByProposed.length > 0 ? triggeredByProposed : [techName],
+            });
+        }
+    }
+    return out;
+}
+/**
+ * The archetype's RISKS: pitfalls the page names for this shape of game,
+ * added when no proposed technique already surfaced them.
+ */
+async function archetypeRiskPitfalls(risks, techNames, seen) {
+    if (risks.length === 0)
+        return [];
+    const fk = await getFalkor();
+    const result = await fk.roQuery(`MATCH (p:Pitfall) WHERE p.name IN $names
+     OPTIONAL MATCH (p)-[:TRIGGERED_BY]->(t:Technique)
+     RETURN p.name AS name, p.title AS title, p.severity AS severity, collect(t.name) AS triggers`, { names: risks });
+    const proposed = new Set(techNames);
+    const out = [];
+    for (const row of parseRows(RiskPitfallRow, result.data)) {
+        if (seen.has(row.name))
+            continue;
+        seen.add(row.name);
+        out.push({
+            name: row.name,
+            title: row.title ?? "",
+            severity: row.severity ?? "low",
+            triggered_by_proposed: presentNames(row.triggers).filter((t) => proposed.has(t)),
+        });
+    }
+    return out;
+}
+/** Per-technique pitfalls first, then archetype risks; sorted by severity, then name. */
+export async function collectPitfalls(techNames, archetypeRisks) {
+    const seen = new Set();
+    const fromTechs = await perTechniquePitfalls(techNames, seen);
+    const fromRisks = await archetypeRiskPitfalls(archetypeRisks, techNames, seen);
+    const rank = (s) => SEVERITY_ORDER.get(s) ?? 4;
+    return [...fromTechs, ...fromRisks].sort((a, b) => rank(a.severity) - rank(b.severity) || a.name.localeCompare(b.name));
+}
+//# sourceMappingURL=plan-pitfalls.js.map

package/dist/tools/briefings/plan-pitfalls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-pitfalls.js","sourceRoot":"","sources":["../../../src/tools/briefings/plan-pitfalls.ts"],"names":[],"mappings":"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"}