productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/interviewGate.js

@@ -0,0 +1,126 @@
+// Interview gate — route a real interview through `interview-me`, and let a single
+// clarifying question through.
+//
+// Why this exists: the first version of this gate was an unconditional deny wired inline
+// into `.claude/settings.json` — every AskUserQuestion in this repo was refused, always,
+// with a message telling the agent to run `interview-me` instead. It fired on an agent
+// that had found the three lines it was asked to edit and wanted to settle ONE thing
+// before editing. There was nothing to interview about. The gate had matched the tool,
+// not the behaviour.
+//
+// That is the same failure this repo already learned from twice in the research gate (B5):
+// a gate that fires on the mention of a risk rather than the risk itself is one people
+// learn to override on sight, and an override reached for on sight protects nothing. The
+// repair is the same one: gate the BEHAVIOUR.
+//
+// An interview has a shape a clarification does not:
+//
+//   THE BATCH. Several questions handed over at once is a questionnaire — the exact thing
+//   `interview-me` forbids ("ask one question at a time"). One question is a clarification.
+//
+//   THE ACCRETION. Question after question after question IS an interview, however each
+//   one was phrased and whatever anyone called it. So the Nth ask in a few minutes trips
+//   the gate: one or two are a clarification and stay free; the third is a run.
+//
+// Both tells are structural. Neither reads the wording of the question, because a gate that
+// guesses at phrasing loses to phrasing it did not guess — that is how the research gate was
+// walked through, and it is not a mistake worth making a third time.
+//
+// The policy lives here, in foo, so any harness can enforce it. Harness configs carry only
+// a thin shim (`.githooks/guard-interview.sh` -> `foo interview gate`).
+//
+// FAILS OPEN on any error. Escape hatch: FOO_ALLOW_VANILLA_INTERVIEW=1.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/** Harnesses disagree on the name of the ask-the-human tool. Accept the ones that exist. */
+const ASK_TOOLS = new Set(["askuserquestion", "ask_user_question", "askuser"]);
+/** Asks older than this stop counting — a question this morning is not this conversation. */
+const ASK_WINDOW_SECONDS = 600;
+/** Single questions that stay free before the counter calls it an interview. */
+const ASK_ALLOWANCE = 2;
+const asksPath = (root) => path.join(root, ".foo", "interview-asks.json");
+const windowMs = () => (Number(process.env.FOO_INTERVIEW_WINDOW_SECONDS ?? ASK_WINDOW_SECONDS) || ASK_WINDOW_SECONDS) * 1000;
+const allowance = () => Number(process.env.FOO_INTERVIEW_ALLOWANCE ?? ASK_ALLOWANCE) || ASK_ALLOWANCE;
+const recentAsks = (root, now) => {
+    const file = asksPath(root);
+    if (!existsSync(file))
+        return [];
+    try {
+        const raw = JSON.parse(readFileSync(file, "utf8"));
+        return (Array.isArray(raw.asks) ? raw.asks : [])
+            .map(Number)
+            .filter((t) => Number.isFinite(t) && now - t < windowMs());
+    }
+    catch {
+        // A corrupt counter must not deny anyone's question.
+        return [];
+    }
+};
+/** Record one question we let through. The accretion trip is only as good as its counter. */
+export function recordInterviewAsk(root, now = Date.now()) {
+    const kept = recentAsks(root, now);
+    kept.push(now);
+    const file = asksPath(root);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ asks: kept }, null, 2)}\n`);
+}
+/** Cleared when a governed interview starts — a real one must not trip its own gate. */
+export function clearInterviewAsks(root) {
+    const file = asksPath(root);
+    if (existsSync(file))
+        rmSync(file, { force: true });
+}
+/** Has the agent asked enough times that this is plainly an interview, unnamed? */
+export function asksLookLikeInterview(root, now = Date.now()) {
+    return recentAsks(root, now).length >= allowance();
+}
+/** How many questions this call hands over at once. A batch is a questionnaire. */
+export function questionCount(call) {
+    const questions = (call.tool_input ?? {}).questions;
+    return Array.isArray(questions) ? questions.length : 1;
+}
+export function evaluateInterviewGate(call, root, env = process.env, now = Date.now()) {
+    if (env.FOO_ALLOW_VANILLA_INTERVIEW)
+        return { allow: true, note: "override" };
+    const tool = (call.tool_name ?? "").trim().toLowerCase();
+    if (!ASK_TOOLS.has(tool))
+        return { allow: true, note: "not-an-ask" };
+    // The batch. Handing over several questions at once is the questionnaire shape, and it is
+    // the one thing interview-me names outright: ask one question at a time.
+    if (questionCount(call) > 1)
+        return { allow: false, reason: BATCH_REASON, note: "batch" };
+    // The accretion. Nobody called this an interview — and it is one. The agent has already
+    // asked its allowance of questions in the last few minutes and is reaching for another.
+    // One question is a clarification; this is a run.
+    if (asksLookLikeInterview(root, now))
+        return { allow: false, reason: ACCRETION_REASON, note: "accretion" };
+    // One question, asked once, to settle something the repo cannot answer. That is not an
+    // interview. It is the thing an agent should do more of, not less.
+    return { allow: true, note: "clarification" };
+}
+const HANDOFF = "  bin/foo spec start <work-item> --request \"<the user's request>\"\n\n" +
+    "then run the interview-me skill (skills/interview-me/SKILL.md) with the Compound Engineering " +
+    "posture: repo-first discovery, explicit scope boundaries, task/validation traceability. Ask one " +
+    "question at a time as numbered text, highest-leverage question first, recommendation marked.";
+// The user's line is not a shorter version of the agent's. It is a different sentence for a
+// different reader: it says what took over and what happens next, in their words. It carries
+// no path, no command and no env var, because none of those are theirs to run — the agent is
+// about to run them. It does not apologise, and it does not read like a crash, because
+// nothing broke: this is foo doing the one thing it is for.
+const BATCH_REASON = {
+    user: "productfoo runs interviews — asking one question at a time instead of all at once.",
+    agent: "this is a questionnaire, not a question: you are handing over several questions at once. " +
+        "productfoo is installed, so an interview runs through foo:\n\n" +
+        HANDOFF +
+        "\n\nAsking one thing you genuinely cannot answer from the repo is fine and is not gated — ask it " +
+        "as a single question. Deliberately going around foo? Set FOO_ALLOW_VANILLA_INTERVIEW=1.",
+};
+const ACCRETION_REASON = {
+    user: "That's a few questions in a row — productfoo is taking the interview from here.",
+    agent: "nobody called this an interview, and it is one: you have already asked the user several questions " +
+        "in the last few minutes and are reaching for another. One question is a clarification; this is a " +
+        "run, and it goes through foo:\n\n" +
+        HANDOFF +
+        "\n\nThis fires on BEHAVIOUR, not on wording — a gate that reads phrasing loses to phrasing it did " +
+        "not anticipate. Deliberately going around foo? Set FOO_ALLOW_VANILLA_INTERVIEW=1.",
+};

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

@@ -0,0 +1,2 @@
+export declare function readJson<T>(file: string): T;
+export declare function readJsonSafe<T>(file: string, fallback: T): T;

package/dist-public/src/jsonFile.js

@@ -0,0 +1,22 @@
+// Reading JSON off disk is one of productfoo's most repeated idioms — the same
+// `JSON.parse(readFileSync(file, "utf8"))`, often wrapped in a try/catch that
+// falls back to a default when the file is missing or corrupt. These two
+// helpers name that idiom once so call sites read as intent, not plumbing.
+import { readFileSync } from "node:fs";
+// Read and parse a JSON file. Throws (ENOENT, or a SyntaxError on malformed
+// content) exactly as the inlined `JSON.parse(readFileSync(...))` did — use
+// this where the caller wants the failure to propagate.
+export function readJson(file) {
+    return JSON.parse(readFileSync(file, "utf8"));
+}
+// Read and parse a JSON file, returning `fallback` if it is missing or its
+// contents cannot be parsed. The no-throw counterpart for reads that must never
+// break over an absent or corrupt file.
+export function readJsonSafe(file, fallback) {
+    try {
+        return readJson(file);
+    }
+    catch {
+        return fallback;
+    }
+}

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

@@ -0,0 +1,182 @@
+import { type ActiveModel } from "./activeModel.js";
+export type BudgetUnit = "usd" | "tokens";
+export type EstimateBasis = "heuristic" | "ledger" | "probed";
+export type Confidence = "low" | "medium" | "high";
+export type OnExceed = "ask" | "stop" | "checkpoint";
+export type PerPassTokens = {
+    observe: number;
+    act: number;
+    verify: number;
+};
+export type ModelMix = {
+    worker: string;
+    verifier: string;
+};
+export type BudgetEstimate = {
+    expected: number;
+    ceiling: number;
+    basis: EstimateBasis;
+    confidence: Confidence;
+    per_pass_tokens: PerPassTokens;
+    model_mix: ModelMix;
+    priced_with: string;
+};
+export type BudgetAgreed = {
+    by: string;
+    at: string;
+    event: string;
+};
+export type BudgetBlock = {
+    unit: BudgetUnit;
+    limit: number;
+    estimate?: BudgetEstimate;
+    agreed?: BudgetAgreed;
+    max_iterations?: number;
+    no_progress_after?: number;
+    on_exceed?: OnExceed;
+    warn_at?: number;
+};
+export type ModelPrice = {
+    input_per_mtok: number;
+    output_per_mtok: number;
+    /**
+     * Assumed effective agent throughput (tokens/sec, incl. tool turns). Optional:
+     * a model with no declared rate yields NO time estimate rather than a made-up
+     * one. Labeled assumption, same status as build_passes (spec-budget-v0 R-008).
+     */
+    tokens_per_sec?: number;
+    /** Model family (claude | gpt | gemini | glm …). Lets a surface ask whether
+     *  foo default-denies autonomy on this model before offering it as an option. */
+    family?: string;
+};
+export type TokenUsage = {
+    fresh_input?: number;
+    cache_write?: number;
+    cache_read?: number;
+    output?: number;
+};
+export type PricingTable = {
+    source: string;
+    date: string;
+    staleAfterDays: number;
+    currency: string;
+    models: Record<string, ModelPrice>;
+    /**
+     * False when the table file is missing — dollar estimates degrade to
+     * token-only instead of throwing (model-roster-data-v0 R-002). Absent means
+     * available (so hand-built fixtures stay valid).
+     */
+    available?: boolean;
+    /** Worded degradation findings carried into every estimate priced on this table. */
+    findings?: string[];
+};
+export declare function parseBudget(raw: unknown, label: string): BudgetBlock;
+export declare function loadPricing(root: string): PricingTable;
+export declare function pricedWith(table: PricingTable): string;
+/** Convert observed token categories with one model's declared dated rates. */
+export declare function priceTokenUsage(table: PricingTable, model: string, usage: TokenUsage): {
+    usd: number;
+    priced_with: string;
+} | null;
+export declare function pricingAgeDays(table: PricingTable, now?: Date): number;
+export declare function pricingIsStale(table: PricingTable, now?: Date): boolean;
+export type MeasureMethod = "count_tokens" | "structural" | "structural_egress_gated";
+/**
+ * `external` = the source is not a local file (a URL, a leaderboard, "arXiv cs.SE").
+ * Its size CANNOT be measured offline, so it is priced with a conservative floor
+ * rather than counted as zero — see EXTERNAL_SOURCE_TOKENS.
+ */
+export type SourceMeasurement = {
+    source: string;
+    found: boolean;
+    tokens: number;
+    external?: boolean;
+};
+export type MeasuredSources = {
+    total: number;
+    measured: SourceMeasurement[];
+    method: MeasureMethod;
+};
+export declare function structuralTokens(text: string): number;
+export declare function measureSources(packetDir: string, sources: string[]): {
+    total: number;
+    measured: SourceMeasurement[];
+};
+/** Does this measurement contain a source whose size we could not actually determine? */
+export declare function hasExternalSources(measured: SourceMeasurement[]): boolean;
+export declare function countTokensViaApi(model: string, text: string, apiKey: string, url?: string): Promise<number>;
+export declare function isLocalOnly(repoCwd: string, source: string, sourcePath: string): boolean;
+export declare function guardSourceForEgress(text: string, localOnly: boolean): {
+    egress: false;
+    reason: string;
+} | {
+    egress: true;
+    text: string;
+};
+export declare function measureSourcesCounted(packetDir: string, sources: string[], opts: {
+    model: string;
+    apiKey?: string;
+    preferApi: boolean;
+    countTokensUrl?: string;
+    routedNonNative?: boolean;
+}): Promise<MeasuredSources>;
+export type EstimateResult = {
+    unit: BudgetUnit;
+    usd: {
+        expected: number;
+        ceiling: number;
+    };
+    tokens: {
+        expected: number;
+        ceiling: number;
+    };
+    expected_iterations: number;
+    ceiling_iterations: number;
+    per_pass_tokens: PerPassTokens;
+    model_mix: ModelMix;
+    model_provenance: {
+        provider: string;
+        family: string;
+        confidence: "confirmed" | "assumed";
+    };
+    basis: EstimateBasis;
+    confidence: Confidence;
+    priced_with: string;
+    measured: SourceMeasurement[];
+    measured_method: MeasureMethod;
+    stale: boolean;
+    stale_age_days: number;
+    /**
+     * False when dollars could not be priced (missing pricing data or an unknown
+     * model): the usd range is zeroed and MUST NOT be trusted — token numbers are
+     * the estimate (model-roster-data-v0 R-002/R-003). Fail-closed consumers
+     * (loop check auto-approval) treat unpriced as at/above the handshake floor.
+     */
+    priced: boolean;
+    /**
+     * True when at least one observation source could not be sized offline (the web).
+     * The token and dollar ranges below then rest on an UNKNOWN and must not be shown
+     * as a prediction — no fabricated "expected .. ceiling". A human may still
+     * authorise the loop, but by setting an explicit spend cap, not by agreeing to a
+     * number foo invented.
+     */
+    unmeasurable: boolean;
+    /** Worded degradation/unknown-model findings. Always worded; a field in --json; glyphs are the caller's job. */
+    findings: string[];
+};
+export declare function estimateLoopBudget(args: {
+    packetDir: string;
+    sources: string[];
+    pricing: PricingTable;
+    unit?: BudgetUnit;
+    budget?: BudgetBlock;
+    now?: Date;
+    measured?: MeasuredSources;
+    active?: ActiveModel;
+}): EstimateResult;
+export declare function buildAgreedBudget(result: EstimateResult, opts: {
+    by: string;
+    at: string;
+    limit?: number;
+}): BudgetBlock;
+export declare function handshakeFloorUsd(): number;