@vibe-hero/server 0.1.0

package/dist/cli/getOffer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file CLI entrypoint for the Stop-hook offer resolver (T037).
+ *
+ * Usage:
+ *   node dist/cli/getOffer.js get-offer --session <sessionId> --tool <toolId>
+ *
+ * Prints a single JSON line to stdout and exits 0. Callers treat any non-zero
+ * exit or non-JSON stdout as "no offer / suppress silently" — this binary must
+ * NEVER produce a non-zero exit that would surface to the user as a hook error.
+ *
+ * Output shapes (always valid JSON on stdout, then newline):
+ *
+ *   {"offer":{"key":"…","title":"…","prompt":"…"}}
+ *   {"suppressed":"cadence"}        (or "declined" | "offers_off" | "no_candidate")
+ *   {"suppressed":"no_candidate"}   (SETUP_REQUIRED or any unexpected result)
+ *
+ * This module is intentionally thin: it validates argv, delegates to the
+ * existing `get_offer` handler (reusing all offer-engine + cadence logic),
+ * and serializes the result. It does NOT re-implement any logic.
+ *
+ * Guard: if VIBE_HERO_STOP_HOOK_ACTIVE=1 is set we are already inside a Stop
+ * hook invocation (the Claude Code host is running the hook again after the
+ * hook itself triggered an action). In that case we exit 0 immediately with a
+ * suppressed result to prevent infinite loops.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md (`get_offer`),
+ * hooks/claude-code/stop-offer.sh, research.md (§ Observation & hook correlation).
+ */
+/**
+ * Entry point. Called when this module is the process entrypoint (`node dist/cli/getOffer.js`).
+ *
+ * Resolves an offer for `sessionId` / `tool` by delegating to the existing
+ * `get_offer` tool handler, then writes the result as JSON and exits 0.
+ * Any error path writes to stderr and falls back to a suppressed result —
+ * the hook must NEVER propagate errors back to the user's session.
+ */
+export declare const main: () => Promise<void>;
+//# sourceMappingURL=getOffer.d.ts.map

package/dist/cli/getOffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getOffer.d.ts","sourceRoot":"","sources":["../../src/cli/getOffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA4FH;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,QAAa,OAAO,CAAC,IAAI,CAwCzC,CAAC"}

package/dist/cli/getOffer.js

@@ -0,0 +1,150 @@
+/**
+ * @file CLI entrypoint for the Stop-hook offer resolver (T037).
+ *
+ * Usage:
+ *   node dist/cli/getOffer.js get-offer --session <sessionId> --tool <toolId>
+ *
+ * Prints a single JSON line to stdout and exits 0. Callers treat any non-zero
+ * exit or non-JSON stdout as "no offer / suppress silently" — this binary must
+ * NEVER produce a non-zero exit that would surface to the user as a hook error.
+ *
+ * Output shapes (always valid JSON on stdout, then newline):
+ *
+ *   {"offer":{"key":"…","title":"…","prompt":"…"}}
+ *   {"suppressed":"cadence"}        (or "declined" | "offers_off" | "no_candidate")
+ *   {"suppressed":"no_candidate"}   (SETUP_REQUIRED or any unexpected result)
+ *
+ * This module is intentionally thin: it validates argv, delegates to the
+ * existing `get_offer` handler (reusing all offer-engine + cadence logic),
+ * and serializes the result. It does NOT re-implement any logic.
+ *
+ * Guard: if VIBE_HERO_STOP_HOOK_ACTIVE=1 is set we are already inside a Stop
+ * hook invocation (the Claude Code host is running the hook again after the
+ * hook itself triggered an action). In that case we exit 0 immediately with a
+ * suppressed result to prevent infinite loops.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md (`get_offer`),
+ * hooks/claude-code/stop-offer.sh, research.md (§ Observation & hook correlation).
+ */
+import { argv, env, stdout, stderr } from "node:process";
+import { makeGetOfferTool } from "../tools/offers.js";
+import { ToolIdSchema } from "../schemas/common.js";
+// ---------------------------------------------------------------------------
+// Infinite-loop guard
+// ---------------------------------------------------------------------------
+/**
+ * If the Stop hook itself triggers Claude Code activity that fires the Stop
+ * hook again, `stop_hook_active` would be `true` in the outer payload. We
+ * communicate that via this env var (set by the shell hook before calling us)
+ * so the CLI can exit immediately rather than re-entering the offer path.
+ */
+const isReentrant = () => env["VIBE_HERO_STOP_HOOK_ACTIVE"] === "1";
+/**
+ * Parse `argv[2..]` into a {@link CliArgs}. Returns `undefined` (and writes a
+ * diagnostic to stderr) when required args are missing or invalid.
+ */
+const parseArgs = (args) => {
+    const [subcommand, ...rest] = args;
+    if (subcommand !== "get-offer") {
+        stderr.write(`vibe-hero cli: unknown subcommand ${JSON.stringify(subcommand ?? "(none)")}; expected "get-offer"\n`);
+        return undefined;
+    }
+    // Simple --key value flag parser (no external deps).
+    const flags = {};
+    for (let i = 0; i < rest.length - 1; i++) {
+        const flag = rest[i];
+        const value = rest[i + 1];
+        if (flag !== undefined && flag.startsWith("--") && value !== undefined && !value.startsWith("--")) {
+            flags[flag.slice(2)] = value;
+            i++; // skip consumed value
+        }
+    }
+    const sessionId = flags["session"];
+    if (!sessionId) {
+        stderr.write("vibe-hero cli: --session <sessionId> is required\n");
+        return undefined;
+    }
+    const rawTool = flags["tool"];
+    if (!rawTool) {
+        stderr.write("vibe-hero cli: --tool <toolId> is required\n");
+        return undefined;
+    }
+    const toolParse = ToolIdSchema.safeParse(rawTool);
+    if (!toolParse.success) {
+        stderr.write(`vibe-hero cli: unknown tool ${JSON.stringify(rawTool)}; valid values: claude-code, codex, kiro-cli, kiro-ide\n`);
+        return undefined;
+    }
+    return { subcommand, sessionId, tool: toolParse.data };
+};
+// ---------------------------------------------------------------------------
+// Suppress result helper
+// ---------------------------------------------------------------------------
+/** Emit a suppressed result and exit 0 (used on all non-offer paths). */
+const suppress = (reason = "no_candidate") => {
+    stdout.write(JSON.stringify({ suppressed: reason }) + "\n");
+    // process.exit is called by the caller after this returns; we don't call it
+    // here so the function remains unit-testable without killing the test process.
+};
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+/**
+ * Entry point. Called when this module is the process entrypoint (`node dist/cli/getOffer.js`).
+ *
+ * Resolves an offer for `sessionId` / `tool` by delegating to the existing
+ * `get_offer` tool handler, then writes the result as JSON and exits 0.
+ * Any error path writes to stderr and falls back to a suppressed result —
+ * the hook must NEVER propagate errors back to the user's session.
+ */
+export const main = async () => {
+    // Infinite-loop guard (FR-019 / research Stop hook).
+    if (isReentrant()) {
+        suppress("no_candidate");
+        return;
+    }
+    const args = parseArgs(argv.slice(2));
+    if (args === undefined) {
+        suppress("no_candidate");
+        return;
+    }
+    // Delegate entirely to the real get_offer handler — no logic duplication.
+    const tool = makeGetOfferTool();
+    let result;
+    try {
+        result = await tool.handler({ sessionId: args.sessionId, tool: args.tool });
+    }
+    catch (err) {
+        stderr.write(`vibe-hero cli: get_offer handler threw unexpectedly: ${String(err)}\n`);
+        suppress("no_candidate");
+        return;
+    }
+    // The handler may return a SETUP_REQUIRED gate sentinel (profile not
+    // configured yet) or a GetOfferResult. In either case we serialize safely.
+    if (typeof result === "object" &&
+        result !== null &&
+        "status" in result &&
+        result.status === "SETUP_REQUIRED") {
+        // Setup not done yet — suppress silently; the hook must not break the session.
+        suppress("no_candidate");
+        return;
+    }
+    stdout.write(JSON.stringify(result) + "\n");
+};
+// ---------------------------------------------------------------------------
+// Entrypoint guard (same pattern as index.ts)
+// ---------------------------------------------------------------------------
+import { fileURLToPath } from "node:url";
+const isEntrypoint = () => {
+    const entry = argv[1];
+    if (entry === undefined)
+        return false;
+    return fileURLToPath(import.meta.url) === entry;
+};
+if (isEntrypoint()) {
+    main().catch((err) => {
+        stderr.write(`vibe-hero cli: fatal: ${String(err)}\n`);
+        // Exit 0 — never propagate errors to the Stop hook caller.
+        process.exitCode = 0;
+    });
+}
+//# sourceMappingURL=getOffer.js.map

package/dist/cli/getOffer.js.map

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

package/dist/cli/index.d.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * @file vibe-hero `bin` dispatcher (T004) — the published CLI entrypoint.
+ *
+ * This is the single `bin` target declared in package.json
+ * (`bin: { "vibe-hero": "dist/cli/index.js" }`). It is a THIN router over the
+ * two existing entry points; it contains NO business logic of its own:
+ *
+ *   - no subcommand, or `mcp`  → start the stdio MCP server ({@link serverMain}
+ *                                from `../index.js`). This is the primary
+ *                                invocation (`npx -y @vibe-hero/server`) used by
+ *                                the plugin's `.mcp.json` (FR-002, FR-008).
+ *   - `get-offer …`            → run the OPTIONAL Stop-hook offer utility
+ *                                ({@link getOfferMain} from `./getOffer.js`),
+ *                                passing the remaining flags through. The Claude
+ *                                Code Stop hook is agent-mediated and does NOT
+ *                                call this (FR-011); it is retained only for
+ *                                non-Claude-Code hosts and debugging.
+ *   - any other subcommand     → a usage line to stderr, nonzero exit.
+ *
+ * Routing keys off `process.argv[2]` (the first user arg). For `get-offer` the
+ * remaining args (`--session`, `--tool`, …) are already on `process.argv`, and
+ * {@link getOfferMain} reads them via `argv.slice(2)` itself — so the dispatcher
+ * does not re-parse or re-pass them.
+ *
+ * Import safety (no double-run): `../index.js` and `./getOffer.js` each auto-run
+ * their own `main` ONLY when THEY are the process entrypoint, via a
+ * `fileURLToPath(import.meta.url) === argv[1]` guard. When this dispatcher is the
+ * entrypoint, `argv[1]` is `dist/cli/index.js`, which never equals either of
+ * their module URLs — so importing their `main` here triggers nothing. This file
+ * carries the SAME guard, so importing IT (e.g. from tests) is likewise
+ * side-effect-free.
+ *
+ * Source of truth: specs/002-distribution/contracts/cli-and-plugin.md,
+ * spec.md FR-002 / FR-008 / FR-011, quickstart.md V2.
+ */
+/**
+ * Route `process.argv` to the correct existing `main`. Returns the selected
+ * `main`'s promise so the caller can await it (and surface a nonzero exit on an
+ * unknown subcommand).
+ *
+ * @param args - The full `process.argv` (the dispatcher reads `args[2]`).
+ * @returns A promise that resolves when the routed entrypoint completes.
+ */
+export declare const dispatch: (args: readonly string[]) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAcH;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAU,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAsBpE,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * @file vibe-hero `bin` dispatcher (T004) — the published CLI entrypoint.
+ *
+ * This is the single `bin` target declared in package.json
+ * (`bin: { "vibe-hero": "dist/cli/index.js" }`). It is a THIN router over the
+ * two existing entry points; it contains NO business logic of its own:
+ *
+ *   - no subcommand, or `mcp`  → start the stdio MCP server ({@link serverMain}
+ *                                from `../index.js`). This is the primary
+ *                                invocation (`npx -y @vibe-hero/server`) used by
+ *                                the plugin's `.mcp.json` (FR-002, FR-008).
+ *   - `get-offer …`            → run the OPTIONAL Stop-hook offer utility
+ *                                ({@link getOfferMain} from `./getOffer.js`),
+ *                                passing the remaining flags through. The Claude
+ *                                Code Stop hook is agent-mediated and does NOT
+ *                                call this (FR-011); it is retained only for
+ *                                non-Claude-Code hosts and debugging.
+ *   - any other subcommand     → a usage line to stderr, nonzero exit.
+ *
+ * Routing keys off `process.argv[2]` (the first user arg). For `get-offer` the
+ * remaining args (`--session`, `--tool`, …) are already on `process.argv`, and
+ * {@link getOfferMain} reads them via `argv.slice(2)` itself — so the dispatcher
+ * does not re-parse or re-pass them.
+ *
+ * Import safety (no double-run): `../index.js` and `./getOffer.js` each auto-run
+ * their own `main` ONLY when THEY are the process entrypoint, via a
+ * `fileURLToPath(import.meta.url) === argv[1]` guard. When this dispatcher is the
+ * entrypoint, `argv[1]` is `dist/cli/index.js`, which never equals either of
+ * their module URLs — so importing their `main` here triggers nothing. This file
+ * carries the SAME guard, so importing IT (e.g. from tests) is likewise
+ * side-effect-free.
+ *
+ * Source of truth: specs/002-distribution/contracts/cli-and-plugin.md,
+ * spec.md FR-002 / FR-008 / FR-011, quickstart.md V2.
+ */
+import { fileURLToPath } from "node:url";
+import { argv, stderr } from "node:process";
+import { main as serverMain } from "../index.js";
+import { main as getOfferMain } from "./getOffer.js";
+/** The bin name, used in the usage line. Matches package.json `bin`. */
+const BIN_NAME = "vibe-hero";
+/** One-line usage shown on stderr for an unknown subcommand. */
+const USAGE = `usage: ${BIN_NAME} [mcp | get-offer --session <id> --tool <toolId>]`;
+/**
+ * Route `process.argv` to the correct existing `main`. Returns the selected
+ * `main`'s promise so the caller can await it (and surface a nonzero exit on an
+ * unknown subcommand).
+ *
+ * @param args - The full `process.argv` (the dispatcher reads `args[2]`).
+ * @returns A promise that resolves when the routed entrypoint completes.
+ */
+export const dispatch = async (args) => {
+    // args[0] = node, args[1] = this script, args[2] = first user subcommand.
+    const subcommand = args[2];
+    // Default (no subcommand) or explicit `mcp` → the stdio MCP server.
+    if (subcommand === undefined || subcommand === "mcp") {
+        await serverMain();
+        return;
+    }
+    // `get-offer` → the optional offer utility. It reads its own flags from
+    // `argv.slice(2)`, so the remaining args pass through untouched.
+    if (subcommand === "get-offer") {
+        await getOfferMain();
+        return;
+    }
+    // Anything else is an error: usage line to stderr, nonzero exit.
+    stderr.write(`${BIN_NAME}: unknown subcommand ${JSON.stringify(subcommand)}\n${USAGE}\n`);
+    process.exitCode = 2;
+};
+/**
+ * Entrypoint guard: only auto-dispatch when this module is the process
+ * entrypoint (`node .../cli/index.js`), not when imported by tests. Mirrors the
+ * `import.meta.url === argv[1]` pattern in `../index.js` and `./getOffer.js`.
+ */
+const isEntrypoint = () => {
+    const entry = argv[1];
+    if (entry === undefined)
+        return false;
+    return fileURLToPath(import.meta.url) === entry;
+};
+if (isEntrypoint()) {
+    dispatch(argv).catch((err) => {
+        stderr.write(`${BIN_NAME}: fatal: ${String(err)}\n`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,eAAe,CAAC;AAErD,wEAAwE;AACxE,MAAM,QAAQ,GAAG,WAAW,CAAC;AAE7B,gEAAgE;AAChE,MAAM,KAAK,GAAG,UAAU,QAAQ,mDAAmD,CAAC;AAEpF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAE,IAAuB,EAAiB,EAAE;IACvE,0EAA0E;IAC1E,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAE3B,oEAAoE;IACpE,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;QACrD,MAAM,UAAU,EAAE,CAAC;QACnB,OAAO;IACT,CAAC;IAED,wEAAwE;IACxE,iEAAiE;IACjE,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;QAC/B,MAAM,YAAY,EAAE,CAAC;QACrB,OAAO;IACT,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,KAAK,CACV,GAAG,QAAQ,wBAAwB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,KAAK,IAAI,CAC5E,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,YAAY,GAAG,GAAY,EAAE;IACjC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACtB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC;AAClD,CAAC,CAAC;AAEF,IAAI,YAAY,EAAE,EAAE,CAAC;IACnB,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACpC,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,YAAY,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tunable assessment configuration (OD-005, research.md).
+ * Pure data — no logic, no imports. All engine modules read from here.
+ * Change values here; nothing is hard-coded across the codebase.
+ */
+export declare const ASSESSMENT_CONFIG: {
+    readonly scale: 400;
+    readonly startingAbility: 300;
+    readonly difficultySeeds: {
+        readonly easy: 200;
+        readonly medium: 300;
+        readonly hard: 400;
+    };
+    readonly kProvisional: 64;
+    readonly kSettled: 24;
+    readonly settleAfterItems: 15;
+    readonly tierCenters: readonly [100, 200, 300, 400, 500];
+    readonly tierBoundaries: readonly [150, 250, 350, 450];
+    readonly hysteresisMargin: 30;
+    readonly dwell: 2;
+    readonly decayHalfLifeDays: 60;
+    readonly stalenessWindowDays: 30;
+    readonly targetOffset: 50;
+    readonly selectWindow: 60;
+    readonly anchorWindow: 20;
+    readonly declineMuteThreshold: 3;
+    readonly backoffBaseHours: 24;
+    readonly backoffFactor: 2;
+    readonly freeFormPassThreshold: 0.6;
+    readonly defaultQuizLength: 4;
+};
+/** Inferred type of the assessment configuration object. */
+export type AssessmentConfig = typeof ASSESSMENT_CONFIG;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;CAkEpB,CAAC;AAEX,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,iBAAiB,CAAC"}

package/dist/config.js

@@ -0,0 +1,63 @@
+/**
+ * Tunable assessment configuration (OD-005, research.md).
+ * Pure data — no logic, no imports. All engine modules read from here.
+ * Change values here; nothing is hard-coded across the codebase.
+ */
+export const ASSESSMENT_CONFIG = {
+    // --- Elo logistic scale -------------------------------------------------
+    // S=400 matches standard chess Elo: a 400-point gap → ~91% win expectation.
+    scale: 400,
+    // Starting ability for a fresh (topic × tool) estimate — mid-scale.
+    startingAbility: 300,
+    // Item difficulty seeds by tag; authored at content creation, NEVER updated
+    // at runtime (two-way Elo would corrupt the scale with a single learner).
+    difficultySeeds: {
+        easy: 200,
+        medium: 300,
+        hard: 400,
+    },
+    // --- K-factor (learning rate) -------------------------------------------
+    // High K while provisional to converge quickly from a cold start.
+    kProvisional: 64,
+    // Smaller K once settled — reduces noise from individual questions.
+    kSettled: 24,
+    // Number of graded items after which the estimate is considered settled.
+    settleAfterItems: 15,
+    // --- Tier centers and boundaries ----------------------------------------
+    // Five tiers spread across the 0–600 ability range.
+    tierCenters: [100, 200, 300, 400, 500],
+    // Boundaries sit halfway between adjacent centers.
+    tierBoundaries: [150, 250, 350, 450],
+    // --- Hysteresis + dwell (anti-flip-flop, FR-008 / SC-014) ---------------
+    // Promote at boundary+30; demote/review only below boundary-30.
+    hysteresisMargin: 30,
+    // Crossing must hold for this many consecutive graded items before acting.
+    dwell: 2,
+    // --- Spaced-review / lapse model (OD-003) --------------------------------
+    // Exponential ability-decay half-life in days (tier-tunable; e.g. 90 for
+    // tier 500 where knowledge is harder-won and decays more slowly).
+    decayHalfLifeDays: 60,
+    // Topic is due for review when days_since_last >= this threshold.
+    stalenessWindowDays: 30,
+    // --- Item selection (OD-005 table) --------------------------------------
+    // Target difficulty = min(θ + targetOffset, nextBoundary + hysteresisMargin).
+    targetOffset: 50,
+    // ± window around the target difficulty in which items are eligible.
+    selectWindow: 60,
+    // One anchor item must fall within ±anchorWindow of the current ability θ.
+    anchorWindow: 20,
+    // --- Offer / decline suppression (FR-020b) ------------------------------
+    // After this many consecutive declines across sessions, mute offers globally.
+    declineMuteThreshold: 3,
+    // Cross-session backoff base delay (hours) after the first decline.
+    backoffBaseHours: 24,
+    // Exponential factor applied per additional consecutive decline.
+    backoffFactor: 2,
+    // --- Free-form judging (OD-002) -----------------------------------------
+    // Minimum fraction of criteria that must be met for a free-form pass.
+    freeFormPassThreshold: 0.6,
+    // --- Quiz length (FR-022) -----------------------------------------------
+    // Default number of items per quiz session; configurable 3–5 by the user.
+    defaultQuizLength: 4,
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,2EAA2E;IAC3E,4EAA4E;IAC5E,KAAK,EAAE,GAAG;IAEV,oEAAoE;IACpE,eAAe,EAAE,GAAG;IAEpB,4EAA4E;IAC5E,0EAA0E;IAC1E,eAAe,EAAE;QACf,IAAI,EAAE,GAAG;QACT,MAAM,EAAE,GAAG;QACX,IAAI,EAAE,GAAG;KACV;IAED,2EAA2E;IAC3E,kEAAkE;IAClE,YAAY,EAAE,EAAE;IAChB,oEAAoE;IACpE,QAAQ,EAAE,EAAE;IACZ,yEAAyE;IACzE,gBAAgB,EAAE,EAAE;IAEpB,2EAA2E;IAC3E,oDAAoD;IACpD,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU;IAC/C,mDAAmD;IACnD,cAAc,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU;IAE7C,2EAA2E;IAC3E,gEAAgE;IAChE,gBAAgB,EAAE,EAAE;IACpB,2EAA2E;IAC3E,KAAK,EAAE,CAAC;IAER,4EAA4E;IAC5E,yEAAyE;IACzE,kEAAkE;IAClE,iBAAiB,EAAE,EAAE;IACrB,kEAAkE;IAClE,mBAAmB,EAAE,EAAE;IAEvB,2EAA2E;IAC3E,8EAA8E;IAC9E,YAAY,EAAE,EAAE;IAChB,qEAAqE;IACrE,YAAY,EAAE,EAAE;IAChB,2EAA2E;IAC3E,YAAY,EAAE,EAAE;IAEhB,2EAA2E;IAC3E,8EAA8E;IAC9E,oBAAoB,EAAE,CAAC;IACvB,oEAAoE;IACpE,gBAAgB,EAAE,EAAE;IACpB,iEAAiE;IACjE,aAAa,EAAE,CAAC;IAEhB,2EAA2E;IAC3E,sEAAsE;IACtE,qBAAqB,EAAE,GAAG;IAE1B,2EAA2E;IAC3E,0EAA0E;IAC1E,iBAAiB,EAAE,CAAC;CACZ,CAAC"}

package/dist/engine/elo.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @file PURE Elo ability-estimation engine (T010, OD-005 / research.md).
+ *
+ * Single-learner Elo: a learner's continuous `ability` (θ) is updated online
+ * against FIXED, authored item difficulties (d). Item difficulty is INPUT DATA
+ * and is never mutated here — only the learner's ability moves (invariant E3).
+ *
+ * This module is IO-FREE and time-free (invariant E5): it never reads the
+ * clock, filesystem, or network. Any time-dependent behaviour (decay,
+ * staleness) lives elsewhere and passes time in explicitly.
+ *
+ * Formulas (OD-005):
+ *   E  = 1 / (1 + 10^((d − θ) / S))          // expected score
+ *   K  = provisional (64) while itemsSeen < settleAfterItems (15), else 24
+ *   θ' = θ + K · (score − E)                  // score ∈ [0,1] partial credit
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/research.md (OD-005);
+ * constants in ../config.ts (ASSESSMENT_CONFIG).
+ */
+/**
+ * Expected score (win probability) of a learner with ability `ability` (θ)
+ * facing an item of difficulty `itemDifficulty` (d), under the logistic Elo
+ * model: `E = 1 / (1 + 10^((d − θ) / scale))`.
+ *
+ * Monotonically increasing in `(θ − d)`: a higher relative ability yields a
+ * higher expected score. When `θ === d` the expectation is exactly `0.5`.
+ *
+ * @param ability - The learner's current ability estimate (θ).
+ * @param itemDifficulty - The item's FIXED authored difficulty (d). Read-only.
+ * @param scale - Logistic scale `S` (default {@link ASSESSMENT_CONFIG.scale}).
+ * @returns The expected score in the open interval (0, 1).
+ */
+export declare const expectedScore: (ability: number, itemDifficulty: number, scale?: number) => number;
+/**
+ * The learning-rate `K` for the next update. High while the estimate is
+ * provisional (cold start) so it converges quickly, then smaller once settled
+ * to damp single-question noise.
+ *
+ * @param itemsSeen - Count of graded items already incorporated for this
+ *   (topic × tool) estimate.
+ * @returns {@link ASSESSMENT_CONFIG.kProvisional} when
+ *   `itemsSeen < ASSESSMENT_CONFIG.settleAfterItems`, otherwise
+ *   {@link ASSESSMENT_CONFIG.kSettled}.
+ */
+export declare const kFactor: (itemsSeen: number) => number;
+/** The result of an ability update: the new ability and incremented count. */
+export interface AbilityUpdate {
+    /** The updated ability estimate θ'. */
+    readonly value: number;
+    /** `itemsSeen` after incorporating this graded item (input + 1). */
+    readonly itemsSeen: number;
+}
+/**
+ * Apply one graded item to a learner's ability estimate (PURE).
+ *
+ * Computes `θ' = θ + K · (score − E)` where `E = expectedScore(θ, d)` and
+ * `K = kFactor(itemsSeen)`, then increments `itemsSeen`. The `score` is partial
+ * credit in `[0, 1]` (e.g. 1 = fully correct, 0 = fully wrong, intermediate for
+ * a partially-met free-form rubric).
+ *
+ * The fixed-difficulty invariant (E3) holds: `itemDifficulty` is read only and
+ * never returned or mutated — this function moves ONLY the learner's ability.
+ *
+ * A correct answer (`score > E`) raises θ; a wrong one (`score < E`) lowers it.
+ * Because the update is proportional to `(score − E)`, a correct answer on a
+ * HARDER item (lower E) raises θ more than the same correct answer on an EASIER
+ * item (higher E).
+ *
+ * @param ability - The learner's current ability estimate (θ).
+ * @param itemsSeen - Graded items already incorporated (≥ 0).
+ * @param itemDifficulty - The item's FIXED authored difficulty (d). Read-only.
+ * @param score - Partial-credit outcome in `[0, 1]`.
+ * @returns The new ability and `itemsSeen + 1`.
+ */
+export declare const updateAbility: (ability: number, itemsSeen: number, itemDifficulty: number, score: number) => AbilityUpdate;
+//# sourceMappingURL=elo.d.ts.map

package/dist/engine/elo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elo.d.ts","sourceRoot":"","sources":["../../src/engine/elo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,MAAM,EACf,gBAAgB,MAAM,EACtB,QAAO,MAAgC,KACtC,MAA8D,CAAC;AAElE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,GAAI,WAAW,MAAM,KAAG,MAGZ,CAAC;AAEjC,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,MAAM,EACf,WAAW,MAAM,EACjB,gBAAgB,MAAM,EACtB,OAAO,MAAM,KACZ,aAOF,CAAC"}

package/dist/engine/elo.js

@@ -0,0 +1,79 @@
+/**
+ * @file PURE Elo ability-estimation engine (T010, OD-005 / research.md).
+ *
+ * Single-learner Elo: a learner's continuous `ability` (θ) is updated online
+ * against FIXED, authored item difficulties (d). Item difficulty is INPUT DATA
+ * and is never mutated here — only the learner's ability moves (invariant E3).
+ *
+ * This module is IO-FREE and time-free (invariant E5): it never reads the
+ * clock, filesystem, or network. Any time-dependent behaviour (decay,
+ * staleness) lives elsewhere and passes time in explicitly.
+ *
+ * Formulas (OD-005):
+ *   E  = 1 / (1 + 10^((d − θ) / S))          // expected score
+ *   K  = provisional (64) while itemsSeen < settleAfterItems (15), else 24
+ *   θ' = θ + K · (score − E)                  // score ∈ [0,1] partial credit
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/research.md (OD-005);
+ * constants in ../config.ts (ASSESSMENT_CONFIG).
+ */
+import { ASSESSMENT_CONFIG } from "../config.js";
+/**
+ * Expected score (win probability) of a learner with ability `ability` (θ)
+ * facing an item of difficulty `itemDifficulty` (d), under the logistic Elo
+ * model: `E = 1 / (1 + 10^((d − θ) / scale))`.
+ *
+ * Monotonically increasing in `(θ − d)`: a higher relative ability yields a
+ * higher expected score. When `θ === d` the expectation is exactly `0.5`.
+ *
+ * @param ability - The learner's current ability estimate (θ).
+ * @param itemDifficulty - The item's FIXED authored difficulty (d). Read-only.
+ * @param scale - Logistic scale `S` (default {@link ASSESSMENT_CONFIG.scale}).
+ * @returns The expected score in the open interval (0, 1).
+ */
+export const expectedScore = (ability, itemDifficulty, scale = ASSESSMENT_CONFIG.scale) => 1 / (1 + 10 ** ((itemDifficulty - ability) / scale));
+/**
+ * The learning-rate `K` for the next update. High while the estimate is
+ * provisional (cold start) so it converges quickly, then smaller once settled
+ * to damp single-question noise.
+ *
+ * @param itemsSeen - Count of graded items already incorporated for this
+ *   (topic × tool) estimate.
+ * @returns {@link ASSESSMENT_CONFIG.kProvisional} when
+ *   `itemsSeen < ASSESSMENT_CONFIG.settleAfterItems`, otherwise
+ *   {@link ASSESSMENT_CONFIG.kSettled}.
+ */
+export const kFactor = (itemsSeen) => itemsSeen < ASSESSMENT_CONFIG.settleAfterItems
+    ? ASSESSMENT_CONFIG.kProvisional
+    : ASSESSMENT_CONFIG.kSettled;
+/**
+ * Apply one graded item to a learner's ability estimate (PURE).
+ *
+ * Computes `θ' = θ + K · (score − E)` where `E = expectedScore(θ, d)` and
+ * `K = kFactor(itemsSeen)`, then increments `itemsSeen`. The `score` is partial
+ * credit in `[0, 1]` (e.g. 1 = fully correct, 0 = fully wrong, intermediate for
+ * a partially-met free-form rubric).
+ *
+ * The fixed-difficulty invariant (E3) holds: `itemDifficulty` is read only and
+ * never returned or mutated — this function moves ONLY the learner's ability.
+ *
+ * A correct answer (`score > E`) raises θ; a wrong one (`score < E`) lowers it.
+ * Because the update is proportional to `(score − E)`, a correct answer on a
+ * HARDER item (lower E) raises θ more than the same correct answer on an EASIER
+ * item (higher E).
+ *
+ * @param ability - The learner's current ability estimate (θ).
+ * @param itemsSeen - Graded items already incorporated (≥ 0).
+ * @param itemDifficulty - The item's FIXED authored difficulty (d). Read-only.
+ * @param score - Partial-credit outcome in `[0, 1]`.
+ * @returns The new ability and `itemsSeen + 1`.
+ */
+export const updateAbility = (ability, itemsSeen, itemDifficulty, score) => {
+    const expected = expectedScore(ability, itemDifficulty);
+    const k = kFactor(itemsSeen);
+    return {
+        value: ability + k * (score - expected),
+        itemsSeen: itemsSeen + 1,
+    };
+};
+//# sourceMappingURL=elo.js.map

package/dist/engine/elo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elo.js","sourceRoot":"","sources":["../../src/engine/elo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,OAAe,EACf,cAAsB,EACtB,QAAgB,iBAAiB,CAAC,KAAK,EAC/B,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,cAAc,GAAG,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;AAElE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAU,EAAE,CACnD,SAAS,GAAG,iBAAiB,CAAC,gBAAgB;IAC5C,CAAC,CAAC,iBAAiB,CAAC,YAAY;IAChC,CAAC,CAAC,iBAAiB,CAAC,QAAQ,CAAC;AAUjC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,OAAe,EACf,SAAiB,EACjB,cAAsB,EACtB,KAAa,EACE,EAAE;IACjB,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IACxD,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7B,OAAO;QACL,KAAK,EAAE,OAAO,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG,QAAQ,CAAC;QACvC,SAAS,EAAE,SAAS,GAAG,CAAC;KACzB,CAAC;AACJ,CAAC,CAAC"}