productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/commands/update.d.ts

@@ -0,0 +1,61 @@
+import { type ClientKind } from "../channelFreshness.js";
+export declare function fetchLatestVersion(registry?: string, timeoutMs?: number): Promise<string | null>;
+export type UpdateAction = "install" | "current" | "unreachable" | "repo";
+export type UpdatePlan = {
+    action: UpdateAction;
+    running: string;
+    latest: string | null;
+    /** Exactly what an install would exec — argv, so a path with a space is not a bug. */
+    argv: string[] | null;
+    /** The same thing, as the line we show the user before running it. */
+    command: string | null;
+};
+export declare function installArgv(kind: ClientKind, latest: string, home?: string): string[] | null;
+export declare function updatePlan(input: {
+    running: string;
+    latest: string | null;
+    kind: ClientKind;
+    home?: string;
+}): UpdatePlan;
+export type UpdateOutcome = {
+    output: string;
+    exitCode: number;
+};
+export type Installer = (argv: string[]) => {
+    status: number | null;
+};
+/**
+ * The offer — the LAST thing a run does, and the only place foo installs
+ * anything you did not ask it to install.
+ *
+ * The same two rules that shape the error-report ask, pulling the same two ways:
+ *
+ *   Never interrupt the work. The question waits until the command has finished
+ *   and printed everything it meant to print. foo learns about the new build
+ *   mid-run (from a response to a request it was already making) and says
+ *   nothing until the work is done.
+ *
+ *   Never hang. Most productfoo runs are piped or agent-driven. A prompt with nobody
+ *   there to answer is not a question, it is a deadlock — so productfoo asks only when
+ *   a real human is on BOTH ends of the terminal, and otherwise prints the one
+ *   line and gets out of the way.
+ *
+ * The answer defaults to no. Silence is not consent — least of all consent to
+ * write to an npm prefix. And a `no` is a real no: foo records that it spoke,
+ * and does not ask again about this build today.
+ */
+export declare function offerUpdate(io?: {
+    stdin?: NodeJS.ReadStream;
+    stderr?: NodeJS.WriteStream;
+    args?: string[];
+    install?: Installer;
+    kind?: ClientKind;
+}): Promise<void>;
+export declare function updateCommand(args?: string[], deps?: {
+    latest?: () => Promise<string | null>;
+    install?: Installer;
+    running?: string;
+    kind?: ClientKind;
+    isTTY?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): Promise<UpdateOutcome>;

package/dist-public/src/commands/update.js

@@ -0,0 +1,244 @@
+// `foo update` — take the build foo just told you about.
+//
+// The notice (updateNotice.ts) says a new version exists. This is the other
+// half: the thing you type when it does. Without it, "0.1.19 is available" ends
+// in a paste — select a long npm string out of a scrollback, trust it, run it —
+// and a tester who is mid-task simply doesn't, which is how someone sits on a
+// stale build for days while being told, correctly, every morning.
+//
+// Four rules:
+//   - UPDATE THE COPY THAT ACTUALLY RUNS. There can be two `foo` installs on one
+//     machine: the global npm one, and the channel one under ~/.foo/versions/dist
+//     that the PATH shim (`~/.foo/bin/foo`) execs. They are different directories,
+//     and `npm install -g` moves only the first. This is not hypothetical — it is
+//     why the owner's `foo` sat on 0.1.18 while a global install of 0.1.20
+//     reported success: the command updated a copy she never ran. An update
+//     command that installs somewhere other than where you are running from is
+//     worse than none, because it lies. So the install target is derived from
+//     where THIS process is executing, never assumed.
+//   - Never update a repo checkout. `npm install` over a dev build would replace
+//     what the developer is editing with a published copy. A repo run refuses.
+//   - Pin the version npm named. A bare package spec installs whatever
+//     is newest at that instant — the same drift the retired Git channel had
+//     when bare `main` floated — while `pkg@0.1.20` installs the build the
+//     user was actually told about.
+//   - Say what it will run before it runs it. This mutates an npm prefix; that
+//     is not something to do behind a spinner.
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { compareVersions, distributionPackageName, fooHome, runningClientKind } from "../channelFreshness.js";
+import { CHANGELOG_URL, clientVersion, pendingUpdate, recordRelaySpoken, recordUpdateSpoken, } from "../updateNotice.js";
+import { glyphsEnabled, withGlyph } from "../statusGlyphs.js";
+// Public updates use npm package metadata. No productfoo account, token or hosted
+// service participates; old private clients retain their existing server path.
+const STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+// Match npm install's effective registry, including local npmrc settings.
+// Config lookup is local; an absent npm executable falls back to public npm.
+function npmRegistry(env, kind) {
+    const configured = env.npm_config_registry?.trim() || env.NPM_CONFIG_REGISTRY?.trim();
+    if (configured)
+        return configured;
+    const args = ["config", "get", "registry"];
+    if (kind === "global")
+        args.push("--global");
+    if (kind === "channel")
+        args.push("--prefix", path.join(fooHome(), "versions", "dist"));
+    const result = spawnSync("npm", args, { env, encoding: "utf8", timeout: 2_000 });
+    return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : DEFAULT_REGISTRY;
+}
+export async function fetchLatestVersion(registry = npmRegistry(process.env), timeoutMs = 10_000) {
+    try {
+        const packageName = distributionPackageName().replace("/", "%2f");
+        const res = await fetch(`${registry.replace(/\/+$/, "")}/${packageName}/latest`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const body = await res.json();
+        return typeof body?.version === "string" && STABLE_VERSION.test(body.version) ? body.version : null;
+    }
+    catch {
+        // Unknown stays unknown: an offline or malformed reply is never proof
+        // that the running copy is current.
+        return null;
+    }
+}
+// What npm installs: the published package at the version npm named,
+// resolved through the ONE distribution-target contract (channelFreshness.ts)
+// — the package name is never hardcoded here, so the owner's final npm
+// identity (or a later successor rename) flows through unchanged.
+//
+// Where the foo that is RUNNING lives decides what npm has to be pointed at to
+// replace it:   global — the ordinary `npm install -g` copy;   channel — the copy
+// under ~/.foo/versions/<channel> that the PATH shim execs, where `-g` would
+// install past it and change nothing the user runs.
+//
+// `--prefix <abs path>`, not the `~/.foo/...` string the docs print: argv is not
+// a shell, and nothing expands a tilde here.
+export function installArgv(kind, latest, home = fooHome()) {
+    const pkg = `${distributionPackageName()}@${latest}`;
+    if (kind === "global")
+        return ["npm", "install", "-g", pkg];
+    if (kind === "channel")
+        return ["npm", "install", "--prefix", path.join(home, "versions", "dist"), pkg];
+    return null; // repo — nothing to install over
+}
+// Pure decision, no network and no npm. Every branch below is a test.
+export function updatePlan(input) {
+    const { running, latest, kind } = input;
+    const none = { running, latest, argv: null, command: null };
+    if (kind === "repo")
+        return { action: "repo", ...none };
+    if (!latest || !STABLE_VERSION.test(latest))
+        return { action: "unreachable", ...none, latest: null };
+    if (compareVersions(running, latest) >= 0)
+        return { action: "current", ...none };
+    const argv = installArgv(kind, latest, input.home ?? fooHome());
+    return { action: "install", running, latest, argv, command: argv ? argv.join(" ") : null };
+}
+const npmInstaller = ([command, ...args]) => spawnSync(command, args, { stdio: "inherit" });
+/**
+ * The offer — the LAST thing a run does, and the only place foo installs
+ * anything you did not ask it to install.
+ *
+ * The same two rules that shape the error-report ask, pulling the same two ways:
+ *
+ *   Never interrupt the work. The question waits until the command has finished
+ *   and printed everything it meant to print. foo learns about the new build
+ *   mid-run (from a response to a request it was already making) and says
+ *   nothing until the work is done.
+ *
+ *   Never hang. Most productfoo runs are piped or agent-driven. A prompt with nobody
+ *   there to answer is not a question, it is a deadlock — so productfoo asks only when
+ *   a real human is on BOTH ends of the terminal, and otherwise prints the one
+ *   line and gets out of the way.
+ *
+ * The answer defaults to no. Silence is not consent — least of all consent to
+ * write to an npm prefix. And a `no` is a real no: foo records that it spoke,
+ * and does not ask again about this build today.
+ */
+export async function offerUpdate(io = {}) {
+    try {
+        const p = pendingUpdate();
+        if (!p)
+            return;
+        const stdin = io.stdin ?? process.stdin;
+        const stderr = io.stderr ?? process.stderr;
+        const args = io.args ?? [];
+        const kind = io.kind ?? runningClientKind();
+        // The agent relay: a line for the coding agent that ran foo to surface to its
+        // human. Never under --json — it would corrupt the payload the agent is
+        // parsing — and when suppressed there, do NOT record, so a later non-json run
+        // in the same session still gets to relay (R-004).
+        if (p.audience === "agent") {
+            if (args.includes("--json"))
+                return;
+            stderr.write(`${p.line}\n`);
+            // Record into the agent's OWN session ration, never the human's day
+            // ration — otherwise a person who also runs foo by hand loses their
+            // interactive offer for the rest of the day (R-001 says it is unchanged).
+            recordRelaySpoken(p.latest);
+            return;
+        }
+        // Whatever happens below, this build has now been spoken about today. Record
+        // it FIRST: if the install throws, or the user ^C's out of the prompt, the
+        // one thing that must not happen is foo re-asking on their very next command.
+        recordUpdateSpoken(p.latest);
+        // Three reasons to state the fact and never ask:
+        //   - nobody is on the other end (piped, hooked, agent-driven);
+        //   - the run is emitting machine output, and a machine cannot answer;
+        //   - it is a repo checkout, where there is nothing to install over anyway.
+        const canAsk = Boolean(stdin.isTTY) && Boolean(stderr.isTTY) && !args.includes("--json") && kind !== "repo";
+        if (!canAsk) {
+            stderr.write(`${p.line}\n`);
+            return;
+        }
+        const plan = updatePlan({ running: p.running, latest: p.latest, kind });
+        if (plan.action !== "install" || !plan.argv) {
+            stderr.write(`${p.line}\n`);
+            return;
+        }
+        const readline = await import("node:readline/promises");
+        const rl = readline.createInterface({ input: stdin, output: stderr });
+        try {
+            stderr.write(`\nfoo ${p.running} → ${p.latest} is available.\n`);
+            stderr.write(`  What's new: ${CHANGELOG_URL}\n`);
+            // Say what the yes DOES. "Install now? [y/N]" hides the fact that a key is
+            // about to write to an npm prefix; someone on a locked-down machine needs
+            // to know which command they are authorizing BEFORE they press y.
+            stderr.write(`  Installing runs: ${plan.command}\n`);
+            const answer = (await rl.question("  Install it now? [y/N] ")).trim().toLowerCase();
+            if (answer !== "y" && answer !== "yes") {
+                stderr.write("  Not installing. Run `foo update` whenever you want it.\n");
+                return;
+            }
+            stderr.write("\n");
+            const result = (io.install ?? npmInstaller)(plan.argv);
+            stderr.write(result.status === 0
+                ? `\nfoo ${p.latest} is installed — it takes effect on your next command.\n`
+                : `\nThe install failed, so you are still on foo ${p.running}. npm's error is above; \`foo update\` retries.\n`);
+        }
+        finally {
+            rl.close();
+        }
+    }
+    catch {
+        // An update offer may never change what the command was asked to do, and may
+        // never be the reason a run fails.
+    }
+}
+export async function updateCommand(args = [], deps = {}) {
+    const env = deps.env ?? process.env;
+    const asJson = args.includes("--json");
+    const checkOnly = args.includes("--check");
+    const glyphs = glyphsEnabled({ isTTY: deps.isTTY ?? Boolean(process.stdout.isTTY), env, args });
+    const running = deps.running ?? clientVersion();
+    const kind = deps.kind ?? runningClientKind();
+    const latest = await (deps.latest ?? (() => fetchLatestVersion(npmRegistry(env, kind))))();
+    const plan = updatePlan({ running, latest, kind });
+    if (asJson) {
+        return {
+            output: `${JSON.stringify({ running: plan.running, latest: plan.latest, state: plan.action, command: plan.command }, null, 2)}\n`,
+            exitCode: plan.action === "unreachable" ? 1 : 0,
+        };
+    }
+    switch (plan.action) {
+        case "repo":
+            // The owner, in the checkout. Nothing to install over, and saying "you are
+            // current" would be meaningless — the repo build is whatever they last
+            // edited. Give them the one fact they might actually want.
+            return {
+                output: `foo ${plan.running} — you're running the repo build, so there is nothing to install over it.${plan.latest ? ` The published release is ${plan.latest}.` : ""}\n`,
+                exitCode: 0,
+            };
+        case "unreachable":
+            return {
+                output: withGlyph("blocked", `blocked — couldn't get a valid latest version from npm, so we can't tell whether ${plan.running} is current. Your install is unchanged; retry with foo update --check.\n`, glyphs),
+                exitCode: 1,
+            };
+        case "current":
+            return { output: withGlyph("proven", `proven — foo ${plan.running} is the newest published build.\n`, glyphs), exitCode: 0 };
+        case "install": {
+            const header = `foo ${plan.running} → ${plan.latest}\nWhat's new: ${CHANGELOG_URL}\n`;
+            if (checkOnly) {
+                // --check is what a script or an agent runs: report, never mutate.
+                return { output: `${header}Update with: foo update\n`, exitCode: 0 };
+            }
+            process.stdout.write(`${header}Running: ${plan.command}\n\n`);
+            const result = (deps.install ?? npmInstaller)(plan.argv);
+            if (result.status !== 0) {
+                // npm already printed its own failure to the inherited stderr; do not
+                // paraphrase it. Say only what the user needs: nothing changed.
+                return {
+                    output: withGlyph("blocked", `\nblocked — the install failed, so you are still on foo ${plan.running}. npm's error is above.\n`, glyphs),
+                    exitCode: 1,
+                };
+            }
+            return {
+                output: withGlyph("proven", `\nproven — foo ${plan.latest} is installed. Check it: foo --version\n`, glyphs),
+                exitCode: 0,
+            };
+        }
+    }
+}

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

@@ -0,0 +1,20 @@
+export interface TurnClassification {
+    miss: boolean;
+    matched: string | null;
+}
+export declare function classifyTurn(text: string): TurnClassification;
+export declare function observeTurn(root: string, turnText: string, at?: string): TurnClassification;
+export interface MissRate {
+    turns: number;
+    misses: number;
+    rate: number | null;
+}
+export declare function missRate(root: string): MissRate;
+export interface LintFinding {
+    file: string;
+    term: string;
+    line: number;
+    text: string;
+}
+export declare function lintShippedSurfaces(root: string): LintFinding[];
+export declare function renderLint(findings: LintFinding[]): string;

package/dist-public/src/comprehensionSignal.js

@@ -0,0 +1,166 @@
+// comprehension-loop-v0 — the comprehension scoreboard and the shipped-surface
+// jargon lint. Both are SIGNALS, never gates (R-004): nothing here blocks,
+// rewrites, or judges output with a model. The scoreboard records when the
+// human had to ask for a translation; the lint reports foo-internal vocabulary
+// on the surfaces that ship to a customer's agent context (commands/, skills/).
+//
+// Boundary, stated where a builder will read it (T-005): comprehension is a
+// signal. Do not add a runtime gate that blocks or rewrites output based on a
+// model's judgment of whether a human understood — that gates on fluency, the
+// exact property that made the bad messages dangerous, and it retypes a
+// surface that produced zero of the nineteen observed complaints. If you are
+// tempted, read specs/comprehension-loop-v0/spec.md R-004 and D-001 first.
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { PM_SURFACE_FORBIDDEN } from "./initCommand.js";
+// --- the translation-request detector (R-001) --------------------------------
+// Deterministic, no model call. Each pattern names the complaint shape it
+// catches; precision is measured against evals/comprehension/, never asserted.
+// Token boundaries are (?<![\w-]) / (?![\w-]) — the researchGate lesson: a
+// substring test is how `cite` once matched "excited".
+const MISS_PATTERNS = [
+    { name: "in-english", re: /(?<![\w-])in (?:plain )?english(?![\w-])/i },
+    { name: "plain-english", re: /(?<![\w-])plain english(?![\w-])/i },
+    { name: "what-does-that-mean", re: /(?<![\w-])what does (?:that|this|it) mean(?![\w-])/i },
+    { name: "translate-that", re: /(?<![\w-])translate (?:that|this|it)(?![\w-])/i },
+    { name: "dont-understand", re: /(?<![\w-])(?:i )?don'?t understand what(?![\w-])/i },
+];
+export function classifyTurn(text) {
+    for (const p of MISS_PATTERNS) {
+        if (p.re.test(text))
+            return { miss: true, matched: p.name };
+    }
+    return { miss: false, matched: null };
+}
+// --- the local scoreboard (D-003: this machine only, no rewrite authority) ---
+const EVENTS_DIR = path.join(".foo", "comprehension");
+const EVENTS_FILE = "events.jsonl";
+export function observeTurn(root, turnText, at = new Date().toISOString()) {
+    const result = classifyTurn(turnText);
+    const dir = path.join(root, EVENTS_DIR);
+    mkdirSync(dir, { recursive: true });
+    const event = {
+        schema_version: "0.1",
+        type: result.miss ? "comprehension_miss" : "turn_observed",
+        at,
+    };
+    if (result.miss) {
+        event.matched = result.matched;
+        // Enough of the turn to audit a false positive later; local-only (.foo/ is
+        // gitignored) and never shipped anywhere.
+        event.excerpt = turnText.slice(0, 160);
+    }
+    appendFileSync(path.join(dir, EVENTS_FILE), `${JSON.stringify(event)}\n`);
+    return result;
+}
+export function missRate(root) {
+    const file = path.join(root, EVENTS_DIR, EVENTS_FILE);
+    if (!existsSync(file))
+        return { turns: 0, misses: 0, rate: null };
+    let turns = 0;
+    let misses = 0;
+    for (const line of readFileSync(file, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (event.type === "comprehension_miss") {
+                turns += 1;
+                misses += 1;
+            }
+            else if (event.type === "turn_observed") {
+                turns += 1;
+            }
+        }
+        catch {
+            // A corrupt line is a log problem, not a reason to fail the scoreboard.
+        }
+    }
+    return { turns, misses, rate: turns === 0 ? null : misses / turns };
+}
+// --- the shipped-surface jargon lint (R-002; a signal, never a block) --------
+// Legitimate internal uses go here, narrowest scope that works: a relative
+// path prefix plus the term it may use. Keep this list short and honest — an
+// allowlist that grows faster than the fixes is the lint being ignored.
+const LINT_ALLOWLIST = [];
+const LINT_ROOTS = ["commands", "skills"];
+function lintFile(root, rel, findings) {
+    const text = readFileSync(path.join(root, rel), "utf8");
+    const lines = text.split("\n");
+    for (const term of PM_SURFACE_FORBIDDEN) {
+        if (LINT_ALLOWLIST.some((a) => rel.startsWith(a.pathPrefix) && a.term === term))
+            continue;
+        const re = new RegExp(`(?<![\\w-])${term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w-])`, "i");
+        for (let i = 0; i < lines.length; i += 1) {
+            if (re.test(lines[i])) {
+                findings.push({ file: rel, term, line: i + 1, text: lines[i].trim().slice(0, 120) });
+                break; // one finding per (file, term) keeps the signal readable
+            }
+        }
+    }
+}
+function walk(root, rel, acc) {
+    const full = path.join(root, rel);
+    if (!existsSync(full))
+        return;
+    // lstat, never stat: skills/ carries adapter symlinks (.codex/ links back
+    // into the repo) and following them walks a loop forever. Dot-entries are
+    // adapter surfaces, not canonical shipped files — skip both.
+    const stat = lstatSync(full);
+    if (stat.isSymbolicLink())
+        return;
+    if (stat.isFile()) {
+        if (rel.endsWith(".md"))
+            acc.push(rel);
+        return;
+    }
+    if (!stat.isDirectory())
+        return;
+    for (const entry of readdirSync(full).sort()) {
+        if (entry.startsWith("."))
+            continue;
+        walk(root, path.join(rel, entry), acc);
+    }
+}
+// comprehension-loop-v0 R-004 — the boundary, written where the next person to
+// extend this lint will read it. Comprehension is a SIGNAL, never a gate. Do not
+// give it a blocking verdict path and do not add a model-judged
+// "did the human understand?" chokepoint: that gates on fluency, which is the exact
+// property that made the observed bad messages dangerous. Signals over gates —
+// a lint that blocks at this detector's precision is switched off within a week,
+// and a signal that keeps its audience beats a gate that loses it.
+export function lintShippedSurfaces(root) {
+    const files = [];
+    for (const dir of LINT_ROOTS)
+        walk(root, dir, files);
+    const findings = [];
+    for (const rel of files)
+        lintFile(root, rel, findings);
+    return findings;
+}
+const LINT_DETAIL_CAP = 20;
+export function renderLint(findings) {
+    if (findings.length === 0)
+        return "shipped surfaces carry no flagged internal vocabulary\n";
+    // A 3,000-line dump is noise wearing a signal's clothes — summarize by file,
+    // show the worst offenders in detail, and NAME what was dropped (no silent
+    // caps): the full list stays one --json away.
+    const byFile = new Map();
+    for (const f of findings)
+        byFile.set(f.file, (byFile.get(f.file) ?? 0) + 1);
+    const worst = [...byFile.entries()].sort((a, b) => b[1] - a[1]);
+    const lines = [
+        `signal: ${findings.length} internal-vocabulary use(s) across ${byFile.size} shipped file(s) (commands/, skills/) — advisory, never a build failure.`,
+        `Worst files first:`,
+    ];
+    for (const [file, count] of worst.slice(0, 10))
+        lines.push(`  ${file} — ${count} term(s)`);
+    lines.push(`First ${Math.min(LINT_DETAIL_CAP, findings.length)} finding(s) in detail:`);
+    for (const f of findings.slice(0, LINT_DETAIL_CAP))
+        lines.push(`  ${f.file}:${f.line} says "${f.term}" — ${f.text}`);
+    if (findings.length > LINT_DETAIL_CAP) {
+        lines.push(`  …and ${findings.length - LINT_DETAIL_CAP} more — run \`foo comprehension lint --json\` for the full list.`);
+    }
+    lines.push("Fix by saying it in the reader's words, or add the narrowest allowlist entry with a reason.");
+    return `${lines.join("\n")}\n`;
+}

package/dist-public/src/conductor/diversity.d.ts

@@ -0,0 +1,48 @@
+export interface IdeaObject {
+    id: string;
+    claim: string;
+    frame: string;
+    lens: string;
+    reasoning: string;
+    mechanism: string;
+    assumption: string;
+    novelty: string;
+    claims_relied_on: string[];
+}
+export interface DiversityMeter {
+    raw: number;
+    distinct_clusters: number;
+    near_dupes_merged: number;
+    exhausted: boolean;
+}
+export interface DiversityComputation extends DiversityMeter {
+    clusters: string[][];
+}
+export declare const CLUSTERER_ID = "idf-cosine-v3-moves";
+export declare const NEAR_DUPE_THRESHOLD = 0.25;
+export declare function featureSet(idea: IdeaObject): Map<string, number>;
+export declare function similarityIn(a: IdeaObject, b: IdeaObject, pool: IdeaObject[]): number;
+export declare function similarity(a: IdeaObject, b: IdeaObject): number;
+export declare function computeDiversity(ideas: IdeaObject[], exhausted?: boolean): DiversityComputation;
+export declare const IDEAS_FENCE_OPEN = "```json ideas";
+export interface IdeaParseResult {
+    ideas: IdeaObject[];
+    errors: string[];
+    present: boolean;
+}
+export declare function parseIdeaObjects(recordText: string): IdeaParseResult;
+export declare const DIVERSITY_METER_LINE: RegExp;
+export declare function readDeclaredMeter(recordText: string): DiversityMeter | null;
+export type DiversityMethod = "measured" | "estimated";
+export declare function readDiversityMethod(recordText: string): {
+    value: DiversityMethod;
+    declared: boolean;
+} | null;
+export declare function readClustererId(recordText: string): string | null;
+export declare function clustererLine(): string;
+export declare function meterLine(meter: DiversityMeter): string;
+export declare const IDEATE_CONTRACT_VERSION = "frames-v1";
+export declare function ideateFrontmatter(record: string): Record<string, unknown> | null;
+export declare function ideateContractVersion(record: string): string | null;
+export declare function hasExecutableFramesContract(recordText: string): boolean;
+export declare function frameReasoningOffenders(ideas: IdeaObject[]): string[];