productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/humanSurfaceEval.js

@@ -0,0 +1,156 @@
+// This registry is intentionally narrow. It catches productfoo's filing system and
+// process chrome, not ordinary product words. In particular, words such as
+// "agent", "task", "spec", and "drift" are valid user language on their own.
+// Token boundaries apply the same false-positive lesson as the research gate:
+// a substring is not evidence that the risky phrase is present.
+const RULES = [
+    {
+        id: "HS-001",
+        pattern: /(?<![\w-])(?:OQ-?\d{1,4}|(?:T|R|C|D)-\d{1,4})(?![\w-])/gi,
+        rewrite: "Remove the internal identifier and ask or state the thing directly.",
+    },
+    {
+        id: "HS-002",
+        pattern: /(?<![\w-])(?:spec_id|done_when|next_action|decision_findings|tasks\.yaml|events\.jsonl)(?![\w-])|\bState:\s*needs-decision\b|\b(?:packet handoff|packet grammar|spec packet|loop contract)\b/gi,
+        rewrite: "Describe the state or next step in ordinary words instead of exposing the storage format.",
+    },
+    {
+        id: "HS-004",
+        pattern: /\b(?:judgment ledger|Shape Brief|product bet|source and approval boundaries|MVP scope|validation bar|human judgment|human is the decider|read-only view of the (?:agent|assistant)|(?:Foo|productfoo) has taken over your default behavior)\b|\b(?:Capability|Skill adapter):/gi,
+        rewrite: "Replace productfoo's filing or process label with what it means for this person.",
+    },
+];
+const PROCESS_LABELS = new Set([
+    "what the assistant sees",
+    "what the agent sees",
+    "thinks",
+    "based on",
+    "would do",
+    "needs you",
+    "updates",
+    "this direction",
+]);
+const PROCESS_LABEL_REWRITE = "Remove the process label and state the useful fact, question, or action directly.";
+function normalizedProcessLabel(line) {
+    let label = line.trim();
+    label = label.replace(/^#{1,6}\s+/, "").replace(/:\s*$/, "").trim();
+    // Markdown decoration does not make productfoo's process chrome user language.
+    // Peel matching emphasis pairs, including nested pairs, before comparison.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const marker of ["**", "__", "*", "_"]) {
+            if (label.length > marker.length * 2 && label.startsWith(marker) && label.endsWith(marker)) {
+                label = label.slice(marker.length, -marker.length).trim();
+                changed = true;
+                break;
+            }
+        }
+    }
+    // productfoo renders the state name as uppercase DRIFT. Lowercase/title-case
+    // "drift" remains ordinary product language and must not be blocked.
+    return label === "DRIFT" || PROCESS_LABELS.has(label.toLocaleLowerCase("en-US")) ? label : undefined;
+}
+function blankInlineCode(line) {
+    const output = [...line];
+    let index = 0;
+    while (index < line.length) {
+        if (line[index] !== "`") {
+            index += 1;
+            continue;
+        }
+        let runEnd = index;
+        while (line[runEnd] === "`")
+            runEnd += 1;
+        const delimiter = line.slice(index, runEnd);
+        const close = line.indexOf(delimiter, runEnd);
+        if (close === -1) {
+            index = runEnd;
+            continue;
+        }
+        output.fill(" ", index, close + delimiter.length);
+        index = close + delimiter.length;
+    }
+    return output.join("");
+}
+function proseLines(text) {
+    const output = [];
+    let fence;
+    for (const [index, raw] of text.split(/\r?\n/).entries()) {
+        const trimmed = raw.trim();
+        const fenceRun = trimmed.match(/^(`{3,}|~{3,})/)?.[1];
+        if (!fence && fenceRun) {
+            fence = { marker: fenceRun[0], length: fenceRun.length };
+            continue;
+        }
+        if (fence) {
+            const closesFence = fenceRun !== undefined &&
+                fenceRun[0] === fence.marker &&
+                fenceRun.length >= fence.length &&
+                trimmed.slice(fenceRun.length).trim() === "";
+            if (closesFence)
+                fence = undefined;
+            continue;
+        }
+        output.push({ line: index + 1, text: blankInlineCode(raw) });
+    }
+    return output;
+}
+export function evaluateHumanSurface(text) {
+    if (!text.trim())
+        return { ok: false, findings: [], error: "empty-input" };
+    const findings = [];
+    for (const candidate of proseLines(text)) {
+        const processLabel = normalizedProcessLabel(candidate.text);
+        if (processLabel) {
+            findings.push({
+                rule: "HS-003",
+                line: candidate.line,
+                phrase: processLabel,
+                rewrite: PROCESS_LABEL_REWRITE,
+            });
+        }
+        for (const rule of RULES) {
+            // RegExp instances with the global flag retain lastIndex. matchAll on a
+            // fresh clone keeps every line independent and finds multiple leaks on
+            // one line without mutating the shared registry.
+            const matches = candidate.text.matchAll(new RegExp(rule.pattern.source, rule.pattern.flags));
+            for (const match of matches) {
+                const phrase = match[0].trim();
+                if (!phrase)
+                    continue;
+                findings.push({ rule: rule.id, line: candidate.line, phrase, rewrite: rule.rewrite });
+            }
+        }
+    }
+    return { ok: findings.length === 0, findings };
+}
+export function renderHumanSurfaceEval(result) {
+    if (result.error === "empty-input")
+        return "No user-facing copy was provided. Pass the draft on stdin and try again.\n";
+    if (result.ok)
+        return "User-facing copy is clear.\n";
+    return [
+        `User-facing copy needs a rewrite (${result.findings.length} finding${result.findings.length === 1 ? "" : "s"}).`,
+        ...result.findings.map((finding) => `- Line ${finding.line}: replace "${finding.phrase}". ${finding.rewrite}`),
+        "Rewrite the draft and run this check again before showing it to the user.",
+        "",
+    ].join("\n");
+}
+export class HumanSurfaceLeakError extends Error {
+    result;
+    constructor(result) {
+        // This error can cross the CLI boundary. Keep its message safe for the
+        // person at the terminal; detailed findings stay on the typed result for
+        // tests and the explicit agent-only stdin evaluator.
+        super("productfoo could not prepare clear user-facing copy. Nothing was shown; update productfoo and try again.");
+        this.name = "HumanSurfaceLeakError";
+        this.result = result;
+    }
+}
+export function guardHumanSurface(text) {
+    const result = evaluateHumanSurface(text);
+    if (!result.ok)
+        throw new HumanSurfaceLeakError(result);
+    return text;
+}

package/dist-public/src/ideate.d.ts

@@ -0,0 +1,43 @@
+import type { FamilyPack } from "./conductor/pack.js";
+import type { Depth, GateResult } from "./conductor/types.js";
+export type IdeateDepth = Depth;
+export interface IdeateTier {
+    depth: IdeateDepth;
+    reframes: number;
+    ideators: number;
+    stress_on: number;
+    judges: number;
+    extra_dissent_round: boolean;
+}
+export declare const MAX_IDEATORS = 8;
+export declare const BUILD_ON_ROUNDS = 1;
+export interface IdeatorCell {
+    ideator: string;
+    frame: string;
+    lens: string;
+    seed: number;
+}
+export declare function tierFromPack(pack: FamilyPack): IdeateTier;
+export declare function cellMatrixFromPack(pack: FamilyPack): IdeatorCell[];
+export interface IdeatePlan {
+    schema_version: "0.1";
+    idea: string;
+    depth: IdeateDepth;
+    tier: IdeateTier;
+    cells: IdeatorCell[];
+    phases: string[];
+    record_path: string;
+    verification: string;
+    handoff: string;
+    decider: "human";
+}
+export declare function planFromPack(pack: FamilyPack, idea: string, at: string): IdeatePlan;
+export declare function scaffoldFromPack(pack: FamilyPack, root: string, idea: string, at: string): string;
+export type IdeateCheckFinding = GateResult["findings"][number];
+export type IdeateCheckResult = GateResult;
+export declare function checkRecordWithPack(pack: FamilyPack, recordText: string): IdeateCheckResult;
+export declare function writeMeasuredMeter(recordText: string, meterText: string): string;
+export declare function runIdeateCommand(root: string, args: string[]): Promise<{
+    output: string;
+    exitCode: number;
+}>;

package/dist-public/src/ideate.js

@@ -0,0 +1,255 @@
+// ideate-command-v0 → methodology-compiler-v0 (T-003) → methodology-as-data
+// (T-004): `foo ideate` is an adapter over the conductor. The family's
+// orchestration lives as DATA and is resolved from the verified local package.
+// A missing family is unavailable while remote delivery is rebuilt. This module
+// imports NO family: it drives the engine from a resolved FamilyPack. The CLI
+// still never generates ideas and never picks a winner (D6).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { buildCells, checkRecord, slugify } from "./conductor/engine.js";
+import { resolveFamilyPack } from "./conductor/familyDelivery.js";
+import { computeDiversity, clustererLine, meterLine, parseIdeaObjects, readDeclaredMeter, DIVERSITY_METER_LINE, } from "./conductor/diversity.js";
+import { contractFromPack, recordFromPack } from "./conductor/pack.js";
+import { markFailure } from "./errorTaxonomy.js";
+import { checkFalsification, decisionResult } from "./conductor/ideateDecision.js";
+import { renderOrchestrationResult } from "./orchestrationResult.js";
+import { findIdeateContext } from "./ideateContext.js";
+export const MAX_IDEATORS = 8;
+export const BUILD_ON_ROUNDS = 1;
+// The engine functions only read a couple of fields off a FamilyDefinition;
+// a pack carries them, so these shims let the generic engine run from pack data.
+function cellsShim(pack) {
+    return { cells: pack.cells };
+}
+function gatesShim(pack) {
+    return { gates: pack.gates, depths: pack.depths };
+}
+export function tierFromPack(pack) {
+    const t = pack.depths[pack.depth];
+    return {
+        depth: pack.depth,
+        reframes: Number(t.reframes),
+        ideators: Number(t.ideators),
+        stress_on: Number(t.stress_on),
+        judges: Number(t.judges),
+        extra_dissent_round: Boolean(t.extra_dissent_round),
+    };
+}
+export function cellMatrixFromPack(pack) {
+    return buildCells(cellsShim(pack), pack.depths[pack.depth]).map((c) => ({
+        ideator: c.role,
+        frame: String(c.attrs.frame),
+        lens: String(c.attrs.lens),
+        seed: Number(c.attrs.seed),
+    }));
+}
+function recordPathFromPack(pack, idea, at) {
+    if (!pack.recordDir)
+        throw new Error(`${pack.family} has no record dir`);
+    return path.posix.join(pack.recordDir, `${at.slice(0, 10)}-${slugify(idea)}.md`);
+}
+export function planFromPack(pack, idea, at) {
+    const recordPath = recordPathFromPack(pack, idea, at);
+    return {
+        schema_version: "0.1",
+        idea,
+        depth: pack.depth,
+        tier: tierFromPack(pack),
+        cells: cellMatrixFromPack(pack),
+        phases: [...pack.phases],
+        record_path: recordPath,
+        verification: `foo ideate check ${recordPath}`,
+        handoff: pack.handoff,
+        decider: "human",
+    };
+}
+// Scaffold a record from a pack: substitute the real idea + timestamp into the
+// pack's pre-rendered frontmatter/body and write it to the real record path.
+export function scaffoldFromPack(pack, root, idea, at) {
+    const rendered = recordFromPack(pack, idea, at);
+    if (!rendered)
+        throw new Error(`${pack.family} has no record template`);
+    const recordPath = recordPathFromPack(pack, idea, at);
+    const full = path.resolve(root, recordPath);
+    if (existsSync(full))
+        throw new Error(`${pack.family} record already exists: ${recordPath}`);
+    mkdirSync(path.dirname(full), { recursive: true });
+    writeFileSync(full, [...rendered.frontmatter, ...rendered.body].join("\n"));
+    return full;
+}
+export function checkRecordWithPack(pack, recordText) {
+    return checkRecord(gatesShim(pack), recordText);
+}
+// --- Diversity (ideate-cost-v1 T-003) -----------------------------------------
+// Rewrite the record's meter with the computed one and mark it measured. The
+// CLI computing this number is the whole point: the orchestrator never reads 70
+// ideas to count near-dupes, so the count stops being a judgment call. `exhausted`
+// is NOT computed — whether the idea space is spent is a run's honest call, so
+// whatever the record already declared survives the rewrite.
+// The clusterer that produced the number is stamped alongside it, so a later
+// reader (and the provenance gate) can tell a current number from one an older,
+// weaker clusterer produced — the meter is only as trustworthy as the code that
+// computed it, and that used to be invisible.
+export function writeMeasuredMeter(recordText, meterText) {
+    const withMeter = recordText.replace(DIVERSITY_METER_LINE, meterText);
+    const withMethod = /^diversity_method:/m.test(withMeter)
+        ? withMeter.replace(/^diversity_method:.*$/m, "diversity_method: measured")
+        : withMeter.replace(meterText, `${meterText}\ndiversity_method: measured`);
+    return /^diversity_clusterer:/m.test(withMethod)
+        ? withMethod.replace(/^diversity_clusterer:.*$/m, clustererLine())
+        : withMethod.replace("diversity_method: measured", `diversity_method: measured\n${clustererLine()}`);
+}
+// --- CLI ----------------------------------------------------------------------
+const LEAN = (process.env.FOO_LEAN_CONTRACT ?? "").trim() === "1";
+export async function runIdeateCommand(root, args) {
+    const json = args.includes("--json");
+    if (args[0] === "context") {
+        const idea = args.slice(1).filter((arg) => arg !== "--json").join(" ").trim();
+        if (!idea)
+            return { output: 'usage: foo ideate context "<idea>" [--json]\n', exitCode: 1 };
+        const context = findIdeateContext(root, idea);
+        return { output: json ? `${JSON.stringify(context, null, 2)}\n` : [
+                "Prior work to read before generating ideas",
+                ...context.candidates.map((c, i) => `${i + 1}. ${c.title} — ${c.path}`),
+                ...(context.candidates.length ? [] : ["No keyword matches found. Inspect related names and user-supplied references before declaring a gap."]),
+                context.limitations, "",
+            ].join("\n"), exitCode: 0 };
+    }
+    if (args[0] === "check" || args[0] === "result") {
+        const target = args[1];
+        if (!target) {
+            markFailure({ errorClass: "usage_error", errorCode: "E_IDEATE_IDEA_MISSING", message: "ideate check: no record given" });
+            return { output: `usage: foo ideate ${args[0]} <record.md> [--json]${args[0] === "check" ? " [--before-build-on]" : ""}\n`, exitCode: 1 };
+        }
+        const full = path.resolve(root, target);
+        if (!existsSync(full)) {
+            markFailure({ errorClass: "not_found", errorCode: "E_SPEC_NOT_FOUND", message: `ideate record not found: ${target}` });
+            return { output: `ideate record not found: ${target}\n`, exitCode: 1 };
+        }
+        // gates are depth-independent; any depth's pack carries the same gate set.
+        const pack = await resolveFamilyPack("ideate", "standard", LEAN);
+        const record = readFileSync(full, "utf8");
+        const early = args[0] === "check" && args.includes("--before-build-on");
+        const errors = early ? checkFalsification(record) : [];
+        const result = early
+            ? { ok: !errors.length, findings: [{ check: "early-falsification", ok: !errors.length, detail: errors.length ? errors.join("; ") : "claim coverage verified; unknowns remain hypotheses, not facts" }] }
+            : checkRecordWithPack(pack, record);
+        if (args[0] === "result" && result.ok) {
+            try {
+                const value = decisionResult(record);
+                return { output: json ? `${JSON.stringify(value, null, 2)}\n` : renderOrchestrationResult(value), exitCode: 0 };
+            }
+            catch (error) {
+                const detail = error.message;
+                return { output: json ? `${JSON.stringify({ ok: false, detail })}\n` : `Cannot render decision: ${detail}\n`, exitCode: 1 };
+            }
+        }
+        if (json)
+            return { output: `${JSON.stringify({ schema_version: "0.1", ...result }, null, 2)}\n`, exitCode: result.ok ? 0 : 1 };
+        const lines = [`ideate check — ${target}`];
+        for (const f of result.findings)
+            lines.push(`  ${f.ok ? "ok " : "FAIL"} ${f.check}: ${f.detail}`);
+        lines.push(result.ok ? (early ? "Early check passes. Continue only with surviving ideas; disclose unknowns and recheck added claims." : "Record verifies: shortlist is contract-complete.") : "Record does not verify — fix the FAIL lines; do not hand off an unverified shortlist.");
+        return { output: `${lines.join("\n")}\n`, exitCode: result.ok ? 0 : 1 };
+    }
+    if (args[0] === "read") {
+        // #700: the pool is stored as machine JSON so the meter can compute from
+        // it — but a human reads ideas, not objects. This renders the stored pool
+        // grouped by computed cluster, claims first, so the record's substance is
+        // readable without parsing anything.
+        const target = args[1];
+        if (!target) {
+            markFailure({ errorClass: "usage_error", errorCode: "E_IDEATE_IDEA_MISSING", message: "ideate read: no record given" });
+            return { output: "usage: foo ideate read <record.md>\n", exitCode: 1 };
+        }
+        const full = path.resolve(root, target);
+        if (!existsSync(full)) {
+            markFailure({ errorClass: "not_found", errorCode: "E_SPEC_NOT_FOUND", message: `ideate record not found: ${target}` });
+            return { output: `ideate record not found: ${target}\n`, exitCode: 1 };
+        }
+        const parsed = parseIdeaObjects(readFileSync(full, "utf8"));
+        if (!parsed.present || parsed.ideas.length === 0) {
+            return { output: "Nothing to read — the record stores no ideas yet.\n", exitCode: 1 };
+        }
+        const byId = new Map(parsed.ideas.map((i) => [i.id, i]));
+        const computed = computeDiversity(parsed.ideas);
+        const lines = [];
+        computed.clusters.forEach((ids, index) => {
+            lines.push(`### C${index + 1}${ids.length > 1 ? ` — ${ids.length} ideas, merged as one move` : ""}`);
+            for (const id of ids) {
+                const idea = byId.get(id);
+                if (!idea)
+                    continue;
+                lines.push("");
+                lines.push(`**${idea.claim}**  — ${id} · ${idea.frame} × ${idea.lens}`);
+                if (idea.reasoning.trim())
+                    lines.push(`- move: ${idea.reasoning}`);
+                lines.push(`- how: ${idea.mechanism}`);
+                lines.push(`- novelty: ${idea.novelty}`);
+                lines.push(`- bet: ${idea.assumption}`);
+            }
+            lines.push("");
+        });
+        return { output: `${lines.join("\n")}\n`, exitCode: 0 };
+    }
+    if (args[0] === "diversity") {
+        const target = args[1];
+        if (!target || target.startsWith("--")) {
+            markFailure({ errorClass: "usage_error", errorCode: "E_IDEATE_IDEA_MISSING", message: "ideate diversity: no record given" });
+            return { output: "usage: foo ideate diversity <record.md> [--write] [--json]\n", exitCode: 1 };
+        }
+        const full = path.resolve(root, target);
+        if (!existsSync(full)) {
+            markFailure({ errorClass: "not_found", errorCode: "E_SPEC_NOT_FOUND", message: `ideate record not found: ${target}` });
+            return { output: `ideate record not found: ${target}\n`, exitCode: 1 };
+        }
+        const text = readFileSync(full, "utf8");
+        const parsed = parseIdeaObjects(text);
+        if (!parsed.present || parsed.errors.length || parsed.ideas.length === 0) {
+            const why = !parsed.present
+                ? "no ideas block in the record — the pools have not stored their objects yet"
+                : parsed.errors.length
+                    ? `stored ideas do not validate: ${parsed.errors.join("; ")}`
+                    : "the ideas block is empty — nothing to cluster";
+            // A refusal by design, not a crash: the record cannot show its work, so
+            // foo declines to hand back a number it would be inventing.
+            markFailure({ errorClass: "gate_block", errorCode: "E_GATE_BLOCKED", message: `ideate diversity: ${why}` });
+            if (json)
+                return { output: `${JSON.stringify({ schema_version: "0.1", ok: false, detail: why }, null, 2)}\n`, exitCode: 1 };
+            return { output: `Cannot measure diversity — ${why}.\nUntil the ideas are stored, the meter is a guess: say diversity_method: estimated.\n`, exitCode: 1 };
+        }
+        const computed = computeDiversity(parsed.ideas, readDeclaredMeter(text)?.exhausted ?? false);
+        const line = meterLine(computed);
+        if (args.includes("--write"))
+            writeFileSync(full, writeMeasuredMeter(text, line));
+        if (json)
+            return { output: `${JSON.stringify({ schema_version: "0.1", ok: true, ...computed }, null, 2)}\n`, exitCode: 0 };
+        const lines = [
+            `ideate diversity — ${target}`,
+            `  ${line}`,
+            `  ${computed.raw} idea(s) merged into ${computed.distinct_clusters} distinct cluster(s); ${computed.near_dupes_merged} near-dupe(s) merged.`,
+            args.includes("--write")
+                ? "Written into the record as diversity_method: measured."
+                : "Not written. Re-run with --write to put this line in the record and mark it measured.",
+        ];
+        return { output: `${lines.join("\n")}\n`, exitCode: 0 };
+    }
+    const depthIdx = args.indexOf("--depth");
+    const depth = (depthIdx === -1 ? "standard" : args[depthIdx + 1]);
+    if (!["fast", "standard", "deep"].includes(depth)) {
+        markFailure({ errorClass: "usage_error", errorCode: "E_BAD_FLAG", message: "ideate: --depth must be fast, standard, or deep" });
+        return { output: "--depth must be fast, standard, or deep\n", exitCode: 1 };
+    }
+    const idea = args.filter((a, i) => !a.startsWith("--") && (depthIdx === -1 || i !== depthIdx + 1)).join(" ").trim();
+    if (!idea) {
+        markFailure({ errorClass: "usage_error", errorCode: "E_IDEATE_IDEA_MISSING", message: "ideate: no idea given" });
+        return { output: 'usage: foo ideate "<raw idea>" [--depth fast|standard|deep] [--json]\n', exitCode: 1 };
+    }
+    const pack = await resolveFamilyPack("ideate", depth, LEAN);
+    const at = new Date().toISOString();
+    scaffoldFromPack(pack, root, idea, at);
+    if (json)
+        return { output: `${JSON.stringify(planFromPack(pack, idea, at), null, 2)}\n`, exitCode: 0 };
+    // The contract array ends with "", so join already carries the trailing newline.
+    return { output: contractFromPack(pack, idea, at).join("\n"), exitCode: 0 };
+}

package/dist-public/src/ideateContext.d.ts

@@ -0,0 +1,11 @@
+export declare function findIdeateContext(root: string, idea: string): {
+    searched: string[];
+    candidates: {
+        path: string;
+        title: string;
+        matched_terms: string[];
+    }[];
+    scanned: number;
+    truncated: boolean;
+    limitations: string;
+};

package/dist-public/src/ideateContext.js

@@ -0,0 +1,83 @@
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+// Read-only, bounded discovery of existing public project artifacts. The agent
+// must read and assess candidates; keyword matches are neither evidence nor a
+// claim that all relevant work was found. Never walk caches/private raw stores.
+const HOMES = ["ideas", "research", "specs", "docs/brainstorms"];
+const SKIP = new Set(["quarantine", "incoming", "raw", "transcripts", "node_modules"]);
+const STOP = new Set("a an and are as at be better by can do for from help how i improve improving in is it make my of on or our should that the this to we what with would".split(" "));
+const words = (value) => [...new Set((value.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter((w) => w.length > 2 && !STOP.has(w)))];
+export function findIdeateContext(root, idea) {
+    const terms = words(idea);
+    const candidates = [];
+    const frequency = new Map();
+    let scanned = 0;
+    let visited = 0;
+    let truncated = false;
+    function walk(relative, depth) {
+        if (depth > 3 || visited >= 1500) {
+            truncated = true;
+            return;
+        }
+        const full = path.join(root, relative);
+        try {
+            let component = root;
+            for (const part of relative.split("/")) {
+                component = path.join(component, part);
+                if (lstatSync(component).isSymbolicLink())
+                    return;
+            }
+            if (!lstatSync(full).isDirectory() || lstatSync(full).isSymbolicLink())
+                return;
+            for (const entry of readdirSync(full, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                if (visited++ >= 1500) {
+                    truncated = true;
+                    break;
+                }
+                if (entry.name.startsWith(".") || SKIP.has(entry.name) || entry.isSymbolicLink())
+                    continue;
+                const rel = path.posix.join(relative, entry.name);
+                if (entry.isDirectory()) {
+                    walk(rel, depth + 1);
+                    continue;
+                }
+                if (!entry.isFile() || !entry.name.endsWith(".md") || entry.name === "AGENTS.md")
+                    continue;
+                scanned++;
+                const file = path.join(root, rel);
+                if (lstatSync(file).size > 128 * 1024) {
+                    truncated = true;
+                    continue;
+                }
+                const body = readFileSync(file, "utf8");
+                if (relative === "ideas" && /^recommendation:\s*null\s*$/m.test(body))
+                    continue;
+                const title = body.match(/^#\s+(.+)$/m)?.[1] ?? entry.name;
+                const filename = new Set(words(rel));
+                const heading = new Set(words(title));
+                const content = new Set(words(body));
+                const matched = terms.filter((term) => filename.has(term) || content.has(term));
+                if (!matched.length)
+                    continue;
+                for (const term of matched)
+                    frequency.set(term, (frequency.get(term) ?? 0) + 1);
+                const weights = matched.map((term) => (filename.has(term) ? 6 : 0) + (heading.has(term) ? 4 : 0) + (content.has(term) ? 1 : 0));
+                candidates.push({ path: rel, title: title.slice(0, 180), matched_terms: matched, weights, score: 0 });
+            }
+        }
+        catch { /* Missing/unreadable homes are reported through discovery limits. */ }
+    }
+    for (const home of HOMES)
+        walk(home, 0);
+    for (const candidate of candidates) {
+        candidate.score = candidate.matched_terms.reduce((score, term, i) => score + candidate.weights[i] * Math.log(1 + scanned / (1 + (frequency.get(term) ?? 0))), 0);
+    }
+    candidates.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+    return {
+        searched: HOMES,
+        candidates: candidates.slice(0, 10).map(({ score: _score, weights: _weights, ...candidate }) => candidate),
+        scanned,
+        truncated: truncated || candidates.length > 10,
+        limitations: "Local keyword discovery only; no match does not prove no prior work. Read candidates, follow their references, distinguish findings from hypotheses, and record gaps. No web or connected sources were queried.",
+    };
+}

package/dist-public/src/index.d.ts

@@ -0,0 +1,2 @@
+export { main, type MainDeps } from "./cli.js";
+export { askToSendReports, createReportRunContext, noteCapsuleFromThisRun, pendingReports, renderReportCommandResult, reportsDir, runReportCommand, writeErrorReport, type ErrorReport, type ReportCommandDeps, type ReportCommandResult, type ReportCommandRun, type ReportFinalizationDeps, type ReportInvocationMode, type ReportRunContext, } from "./errorReport.js";

package/dist-public/src/index.js

@@ -0,0 +1,4 @@
+// Supported package entrypoint: CLI bootstrap and local diagnostic report API.
+// The export map and docs/library-exports.md define the consumer contract.
+export { main } from "./cli.js";
+export { askToSendReports, createReportRunContext, noteCapsuleFromThisRun, pendingReports, renderReportCommandResult, reportsDir, runReportCommand, writeErrorReport, } from "./errorReport.js";

package/dist-public/src/initCommand.d.ts

@@ -0,0 +1,25 @@
+import { type SurveyIO } from "./profile.js";
+export declare const FIRST_RUN_OPENER: readonly string[];
+export declare const NO_REPO_STORY: readonly string[];
+export declare function scaffoldPacket(root: string, title: string, evidence: string[], intent: string): string;
+type InitOptions = {
+    json: boolean;
+    pick: number | null;
+    intent: string | null;
+    pm: boolean;
+    attachProof: string | null;
+};
+export declare function parseInitArgs(args: string[]): InitOptions;
+import { JARGON_TERMS } from "./productDetect.js";
+export { JARGON_TERMS as PM_SURFACE_FORBIDDEN };
+export declare function pmSurfaceLeaks(text: string): string[];
+export declare function runInit(root: string, args: string[]): string;
+export declare function initHandoffSteps(root: string): string[];
+export declare function surveyApplies(root: string, args: string[], io: {
+    inputTTY: boolean;
+    outputTTY: boolean;
+}): boolean;
+export declare function runInitInteractive(root: string, args: string[], io?: SurveyIO & {
+    inputTTY?: boolean;
+    outputTTY?: boolean;
+}): Promise<string>;