@vibe-hero/server 0.1.0

package/dist/engine/selection.js

@@ -0,0 +1,119 @@
+/**
+ * @file PURE item-selection engine (T011, OD-005 / research.md).
+ *
+ * Chooses the items for one quiz session for a single (topic × class) given the
+ * learner's current ability θ, the topic's candidate items (with FIXED authored
+ * difficulties), the target tier's next boundary, and a recent-item exclusion
+ * set. Difficulty-targets at the promotion bar so "passing a set" ≈ "ready to
+ * graduate", while an information-weighted window avoids always serving the
+ * hardest item.
+ *
+ * This module is IO-FREE and time-free (E5) and never mutates item difficulty
+ * (E3): items are read-only inputs.
+ *
+ * Selection rule (OD-005):
+ *   target = min(θ + targetOffset, nextBoundary + hysteresisMargin)
+ *   pool   = items with |difficulty − target| ≤ selectWindow, excluding recents
+ *   weight = p · (1 − p), p = expectedScore(θ, difficulty)  // Fisher info ∝ p(1−p)
+ *   pick `length` items by weight; ALWAYS include one "anchor" item within
+ *   ±anchorWindow of θ if one exists in the pool.
+ *
+ * Determinism: this function NEVER calls `Math.random`. Sampling is deterministic
+ * given the inputs. By default it picks the top-weighted items (ties broken by
+ * item id for total order). Callers that want stochastic-but-reproducible
+ * sampling may inject a seeded {@link Rng}; the same seed ⇒ the same output.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/research.md (OD-005);
+ * constants in ../config.ts (ASSESSMENT_CONFIG).
+ */
+import { ASSESSMENT_CONFIG } from "../config.js";
+import { expectedScore } from "./elo.js";
+/**
+ * Total ordering used to break ties deterministically: descending weight, then
+ * ascending item id. Guarantees a single canonical order for equal weights so
+ * the default (RNG-free) path is fully reproducible.
+ */
+const byWeightThenId = (a, b) => b.weight - a.weight || (a.item.id < b.item.id ? -1 : a.item.id > b.item.id ? 1 : 0);
+/**
+ * Draw `count` items from `pool` proportional to weight using an injected RNG,
+ * without replacement. Deterministic for a given RNG sequence. Falls back to
+ * uniform choice if all remaining weights are zero.
+ */
+const weightedSampleWithoutReplacement = (pool, count, rng) => {
+    const remaining = [...pool];
+    const picked = [];
+    while (picked.length < count && remaining.length > 0) {
+        const total = remaining.reduce((sum, c) => sum + c.weight, 0);
+        let index = 0;
+        if (total > 0) {
+            const threshold = rng() * total;
+            let acc = 0;
+            for (let i = 0; i < remaining.length; i++) {
+                acc += remaining[i].weight;
+                if (acc >= threshold) {
+                    index = i;
+                    break;
+                }
+            }
+        }
+        else {
+            // All-zero weights: uniform pick over the remaining pool.
+            index = Math.min(remaining.length - 1, Math.floor(rng() * remaining.length));
+        }
+        picked.push(remaining[index].item);
+        remaining.splice(index, 1);
+    }
+    return picked;
+};
+/**
+ * Select 3–5 items for a quiz session (PURE; see file header for the rule).
+ *
+ * Items are read-only inputs; their difficulty is never mutated (E3). No clock,
+ * file, or network access (E5). Output is deterministic for identical inputs
+ * (and identical injected {@link Rng} sequence, if any).
+ *
+ * Behaviour summary:
+ * - Builds `target = min(θ + targetOffset, nextBoundary + hysteresisMargin)`.
+ * - Pool = candidates within ±`selectWindow` of `target`, excluding
+ *   `recentItemIds`.
+ * - Weights each by `p·(1−p)` (`p = expectedScore(θ, difficulty)`).
+ * - Guarantees one anchor item within ±`anchorWindow` of θ (the most
+ *   informative such item) is included when one exists in the pool.
+ * - Returns at most `length` items; fewer if the pool is smaller.
+ *
+ * @returns The chosen items, length ≤ `length`, anchor-first when an anchor
+ *   exists, then the remaining picks.
+ */
+export const selectItems = (params) => {
+    const { ability, candidates, nextBoundary, recentItemIds = [], length = ASSESSMENT_CONFIG.defaultQuizLength, rng, } = params;
+    if (length <= 0)
+        return [];
+    const { targetOffset, hysteresisMargin, selectWindow, anchorWindow } = ASSESSMENT_CONFIG;
+    const target = Math.min(ability + targetOffset, nextBoundary + hysteresisMargin);
+    const excluded = new Set(recentItemIds);
+    // Eligible pool: within ±selectWindow of target, not recently served.
+    const pool = candidates
+        .filter((item) => !excluded.has(item.id) &&
+        Math.abs(item.difficulty - target) <= selectWindow)
+        .map((item) => {
+        const p = expectedScore(ability, item.difficulty);
+        return { item, weight: p * (1 - p) };
+    });
+    if (pool.length === 0)
+        return [];
+    // Pick the anchor: most-informative item within ±anchorWindow of θ.
+    // Deterministic ordering guarantees a stable choice on ties.
+    const anchorPool = pool
+        .filter((c) => Math.abs(c.item.difficulty - ability) <= anchorWindow)
+        .sort(byWeightThenId);
+    const anchor = anchorPool[0]?.item;
+    const remainingNeeded = anchor ? length - 1 : length;
+    const rest = pool.filter((c) => c.item.id !== anchor?.id);
+    const chosenRest = remainingNeeded <= 0
+        ? []
+        : rng
+            ? weightedSampleWithoutReplacement(rest, remainingNeeded, rng)
+            : [...rest].sort(byWeightThenId).slice(0, remainingNeeded).map((c) => c.item);
+    return anchor ? [anchor, ...chosenRest] : chosenRest;
+};
+//# sourceMappingURL=selection.js.map

package/dist/engine/selection.js.map

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

package/dist/grading/deterministic.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @file PURE deterministic grading (T030, FR-011, SC-004).
+ *
+ * Grades the two deterministic question types — `multiple_choice` and
+ * `short_answer` — entirely in-engine, with NO IO, NO clock, and NO host-agent
+ * involvement. Grading is objective and **reproducible**: the same item + same
+ * answer always yields the same `score` and `Grade` (SC-004). Free-form grading
+ * is the host-agent verdict handshake and lives elsewhere (T048); this module
+ * never touches it.
+ *
+ * Both graders return a continuous `score ∈ {0, 1}` (deterministic items are
+ * all-or-nothing — there is no partial credit for MC/short-answer), which the
+ * Elo engine consumes, plus enough context for the caller to build the
+ * `submit_answer` result (`correctChoiceId` for MC). The binary {@link Grade}
+ * projection is derived from the score via {@link toGrade} against the item's
+ * pass threshold.
+ *
+ * Invariants (mirrors engine/elo.ts, engine/selection.ts):
+ *  - PURE: no `Date`, no `fs`, no `Math.random`, no network.
+ *  - Item difficulty is read-only input — never mutated here (E3).
+ *  - Determinism: identical inputs ⇒ identical outputs (SC-004).
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`submit_answer` deterministic path), spec.md FR-011 / SC-004,
+ * data-model.md (Grade = binary projection of a continuous score).
+ */
+import type { ContentItem } from "../schemas/content.js";
+import type { Grade } from "../schemas/common.js";
+/** Result of grading a `multiple_choice` item. */
+export interface MultipleChoiceGrade {
+    /** All-or-nothing score: `1` if the chosen id matches the key, else `0`. */
+    readonly score: 0 | 1;
+    /** The authored correct choice id (for the `submit_answer` `correctAnswer`). */
+    readonly correctChoiceId: string;
+}
+/** Result of grading a `short_answer` item. */
+export interface ShortAnswerGrade {
+    /** All-or-nothing score: `1` if the normalized text matches a key, else `0`. */
+    readonly score: 0 | 1;
+}
+/**
+ * Apply a `short_answer` answer key's `normalize` directive to a string before
+ * comparison. Pure and idempotent:
+ *  - `"lower"` → lowercase only.
+ *  - `"trim"`  → trim leading/trailing whitespace only.
+ *  - `"both"`  → trim then lowercase.
+ *  - omitted   → exact comparison (no normalization).
+ *
+ * @param value - The raw string (user text or an authored keyword).
+ * @param normalize - The key's normalization mode, if any.
+ * @returns The normalized string.
+ */
+export declare const applyNormalize: (value: string, normalize: "lower" | "trim" | "both" | undefined) => string;
+/**
+ * Grade a `multiple_choice` item (PURE, reproducible).
+ *
+ * Compares the submitted `choiceId` to the item's `answerKey.correctChoiceId`.
+ * The score is `1` for an exact id match, `0` otherwise; the correct choice id
+ * is returned regardless so the caller can surface it after grading.
+ *
+ * @param item - The catalog item being graded (must be `multiple_choice` with a
+ *   `choice` answer key — guaranteed by {@link ContentItem} validation).
+ * @param choiceId - The choice id the user selected (may be `undefined` if the
+ *   user submitted no/blank choice, which scores `0`).
+ * @returns The score and the authored correct choice id.
+ * @throws {Error} if the item is not a `multiple_choice` item with a `choice`
+ *   answer key (a programming error — the catalog schema forbids it).
+ */
+export declare const gradeMultipleChoice: (item: ContentItem, choiceId: string | undefined) => MultipleChoiceGrade;
+/**
+ * Grade a `short_answer` item (PURE, reproducible).
+ *
+ * Applies the key's `normalize` directive to BOTH the user's text and each
+ * accepted keyword, then scores `1` if the normalized user text equals any
+ * accepted keyword (`anyOf`), else `0`. Normalizing both sides keeps the match
+ * symmetric (the same rule applied to authored keys and user input).
+ *
+ * @param item - The catalog item being graded (must be `short_answer` with a
+ *   `keyword` answer key — guaranteed by {@link ContentItem} validation).
+ * @param text - The user's free-text answer (may be `undefined` if the user
+ *   submitted no/blank text, which scores `0`).
+ * @returns The all-or-nothing score.
+ * @throws {Error} if the item is not a `short_answer` item with a `keyword`
+ *   answer key (a programming error — the catalog schema forbids it).
+ */
+export declare const gradeShortAnswer: (item: ContentItem, text: string | undefined) => ShortAnswerGrade;
+/**
+ * Project a continuous `score ∈ [0, 1]` to the binary {@link Grade} persisted in
+ * history: `score ≥ passThreshold ⇒ "correct"`, else `"incorrect"`
+ * (data-model.md / research.md). The same projection serves deterministic
+ * (score ∈ {0, 1}) and free-form (fractional score) grades, keeping one
+ * definition of "correct".
+ *
+ * For deterministic items the natural threshold is any value in `(0, 1]` (e.g.
+ * the default `1`), so a `0` is always incorrect and a `1` always correct.
+ *
+ * @param score - The continuous outcome in `[0, 1]`.
+ * @param passThreshold - The fraction at/above which the grade is `"correct"`.
+ * @returns The derived binary grade.
+ */
+export declare const toGrade: (score: number, passThreshold: number) => Grade;
+//# sourceMappingURL=deterministic.d.ts.map

package/dist/grading/deterministic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministic.d.ts","sourceRoot":"","sources":["../../src/grading/deterministic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,MAAM,EACb,WAAW,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,KAC/C,MAWF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC9B,MAAM,WAAW,EACjB,UAAU,MAAM,GAAG,SAAS,KAC3B,mBAWF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,WAAW,EACjB,MAAM,MAAM,GAAG,SAAS,KACvB,gBAcF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,EAAE,eAAe,MAAM,KAAG,KACb,CAAC"}

package/dist/grading/deterministic.js

@@ -0,0 +1,118 @@
+/**
+ * @file PURE deterministic grading (T030, FR-011, SC-004).
+ *
+ * Grades the two deterministic question types — `multiple_choice` and
+ * `short_answer` — entirely in-engine, with NO IO, NO clock, and NO host-agent
+ * involvement. Grading is objective and **reproducible**: the same item + same
+ * answer always yields the same `score` and `Grade` (SC-004). Free-form grading
+ * is the host-agent verdict handshake and lives elsewhere (T048); this module
+ * never touches it.
+ *
+ * Both graders return a continuous `score ∈ {0, 1}` (deterministic items are
+ * all-or-nothing — there is no partial credit for MC/short-answer), which the
+ * Elo engine consumes, plus enough context for the caller to build the
+ * `submit_answer` result (`correctChoiceId` for MC). The binary {@link Grade}
+ * projection is derived from the score via {@link toGrade} against the item's
+ * pass threshold.
+ *
+ * Invariants (mirrors engine/elo.ts, engine/selection.ts):
+ *  - PURE: no `Date`, no `fs`, no `Math.random`, no network.
+ *  - Item difficulty is read-only input — never mutated here (E3).
+ *  - Determinism: identical inputs ⇒ identical outputs (SC-004).
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`submit_answer` deterministic path), spec.md FR-011 / SC-004,
+ * data-model.md (Grade = binary projection of a continuous score).
+ */
+/**
+ * Apply a `short_answer` answer key's `normalize` directive to a string before
+ * comparison. Pure and idempotent:
+ *  - `"lower"` → lowercase only.
+ *  - `"trim"`  → trim leading/trailing whitespace only.
+ *  - `"both"`  → trim then lowercase.
+ *  - omitted   → exact comparison (no normalization).
+ *
+ * @param value - The raw string (user text or an authored keyword).
+ * @param normalize - The key's normalization mode, if any.
+ * @returns The normalized string.
+ */
+export const applyNormalize = (value, normalize) => {
+    switch (normalize) {
+        case "lower":
+            return value.toLowerCase();
+        case "trim":
+            return value.trim();
+        case "both":
+            return value.trim().toLowerCase();
+        case undefined:
+            return value;
+    }
+};
+/**
+ * Grade a `multiple_choice` item (PURE, reproducible).
+ *
+ * Compares the submitted `choiceId` to the item's `answerKey.correctChoiceId`.
+ * The score is `1` for an exact id match, `0` otherwise; the correct choice id
+ * is returned regardless so the caller can surface it after grading.
+ *
+ * @param item - The catalog item being graded (must be `multiple_choice` with a
+ *   `choice` answer key — guaranteed by {@link ContentItem} validation).
+ * @param choiceId - The choice id the user selected (may be `undefined` if the
+ *   user submitted no/blank choice, which scores `0`).
+ * @returns The score and the authored correct choice id.
+ * @throws {Error} if the item is not a `multiple_choice` item with a `choice`
+ *   answer key (a programming error — the catalog schema forbids it).
+ */
+export const gradeMultipleChoice = (item, choiceId) => {
+    if (item.type !== "multiple_choice" || item.answerKey?.kind !== "choice") {
+        throw new Error(`gradeMultipleChoice: item ${JSON.stringify(item.id)} is not a multiple_choice item with a choice answer key`);
+    }
+    const correctChoiceId = item.answerKey.correctChoiceId;
+    return {
+        score: choiceId === correctChoiceId ? 1 : 0,
+        correctChoiceId,
+    };
+};
+/**
+ * Grade a `short_answer` item (PURE, reproducible).
+ *
+ * Applies the key's `normalize` directive to BOTH the user's text and each
+ * accepted keyword, then scores `1` if the normalized user text equals any
+ * accepted keyword (`anyOf`), else `0`. Normalizing both sides keeps the match
+ * symmetric (the same rule applied to authored keys and user input).
+ *
+ * @param item - The catalog item being graded (must be `short_answer` with a
+ *   `keyword` answer key — guaranteed by {@link ContentItem} validation).
+ * @param text - The user's free-text answer (may be `undefined` if the user
+ *   submitted no/blank text, which scores `0`).
+ * @returns The all-or-nothing score.
+ * @throws {Error} if the item is not a `short_answer` item with a `keyword`
+ *   answer key (a programming error — the catalog schema forbids it).
+ */
+export const gradeShortAnswer = (item, text) => {
+    if (item.type !== "short_answer" || item.answerKey?.kind !== "keyword") {
+        throw new Error(`gradeShortAnswer: item ${JSON.stringify(item.id)} is not a short_answer item with a keyword answer key`);
+    }
+    if (text === undefined)
+        return { score: 0 };
+    const { anyOf, normalize } = item.answerKey;
+    const normalizedText = applyNormalize(text, normalize);
+    const matches = anyOf.some((keyword) => applyNormalize(keyword, normalize) === normalizedText);
+    return { score: matches ? 1 : 0 };
+};
+/**
+ * Project a continuous `score ∈ [0, 1]` to the binary {@link Grade} persisted in
+ * history: `score ≥ passThreshold ⇒ "correct"`, else `"incorrect"`
+ * (data-model.md / research.md). The same projection serves deterministic
+ * (score ∈ {0, 1}) and free-form (fractional score) grades, keeping one
+ * definition of "correct".
+ *
+ * For deterministic items the natural threshold is any value in `(0, 1]` (e.g.
+ * the default `1`), so a `0` is always incorrect and a `1` always correct.
+ *
+ * @param score - The continuous outcome in `[0, 1]`.
+ * @param passThreshold - The fraction at/above which the grade is `"correct"`.
+ * @returns The derived binary grade.
+ */
+export const toGrade = (score, passThreshold) => score >= passThreshold ? "correct" : "incorrect";
+//# sourceMappingURL=deterministic.js.map

package/dist/grading/deterministic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministic.js","sourceRoot":"","sources":["../../src/grading/deterministic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAmBH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,KAAa,EACb,SAAgD,EACxC,EAAE;IACV,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;QAC7B,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACpC,KAAK,SAAS;YACZ,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,IAAiB,EACjB,QAA4B,EACP,EAAE;IACvB,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB,IAAI,IAAI,CAAC,SAAS,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;QACzE,MAAM,IAAI,KAAK,CACb,6BAA6B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,yDAAyD,CAC9G,CAAC;IACJ,CAAC;IACD,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC;IACvD,OAAO;QACL,KAAK,EAAE,QAAQ,KAAK,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3C,eAAe;KAChB,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,IAAiB,EACjB,IAAwB,EACN,EAAE;IACpB,IAAI,IAAI,CAAC,IAAI,KAAK,cAAc,IAAI,IAAI,CAAC,SAAS,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CACb,0BAA0B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,uDAAuD,CACzG,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAE5C,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;IAC5C,MAAM,cAAc,GAAG,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CACxB,CAAC,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC,KAAK,cAAc,CACnE,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACpC,CAAC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,aAAqB,EAAS,EAAE,CACrE,KAAK,IAAI,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC"}

package/dist/grading/freeform.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file PURE free-form grading (T048, FR-012/013, US-4).
+ *
+ * Scores a free-form item from the host agent's **per-criterion** verdict against
+ * the item's MCP-supplied {@link Rubric}. The score is the FRACTION of rubric
+ * criteria the agent marked `met`; the binary {@link Grade} is the projection of
+ * that score against the rubric's `passThreshold` (default
+ * {@link ASSESSMENT_CONFIG.freeFormPassThreshold} = 0.6) via the shared
+ * {@link toGrade} (one definition of "correct" across deterministic + free-form).
+ *
+ * Anti-gaming (critique E2, FR-013): the verdict MUST be a per-criterion array
+ * that aligns to the rubric's criteria ids. This module REJECTS a bare boolean,
+ * a missing/empty criteria array, an unknown criterion id, or a verdict that
+ * does not cover every rubric criterion — a lazy single self-pass is
+ * non-conformant and never silently scored. The host agent cannot invent its own
+ * criteria: only ids present in the authoritative rubric are accepted.
+ *
+ * Invariants (mirrors grading/deterministic.ts, engine/elo.ts):
+ *  - PURE: no `Date`, no `fs`, no `Math.random`, no network.
+ *  - The rubric is read-only input — never mutated here.
+ *  - Determinism: identical verdict + rubric ⇒ identical score + grade.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`submit_answer` free-form path), spec.md FR-012 / FR-013, research.md
+ * (OD-002 — free-form IN v1, `freeFormPassThreshold` 0.6), data-model.md
+ * (Grade = binary projection of a continuous score).
+ */
+import type { Grade } from "../schemas/common.js";
+import type { Rubric } from "../schemas/content.js";
+import type { FreeFormVerdict } from "../schemas/tools.js";
+/** The outcome of scoring a free-form verdict against its rubric. */
+export interface FreeFormGrade {
+    /** Fraction of rubric criteria the agent marked `met`, in `[0, 1]`. */
+    readonly score: number;
+    /** Binary projection of `score` against the rubric's pass threshold. */
+    readonly grade: Grade;
+}
+/**
+ * Score a free-form item from the host agent's per-criterion verdict (PURE).
+ *
+ * The score is `metCount / rubric.criteria.length` — the fraction of the
+ * authoritative rubric criteria the agent reported as met. The grade derives
+ * from that score against the rubric's `passThreshold` (falling back to
+ * {@link ASSESSMENT_CONFIG.freeFormPassThreshold} when the rubric omits one).
+ *
+ * The verdict is validated for SHAPE before scoring (anti-gaming, FR-013):
+ *  - it MUST carry a non-empty `criteria` array (a bare boolean / missing
+ *    criteria is rejected — the SDK union also rejects it, this is defence in
+ *    depth so a direct caller can't bypass the structure);
+ *  - every verdict criterion id MUST reference a real rubric criterion id (the
+ *    agent cannot invent criteria);
+ *  - no rubric criterion id may be duplicated in the verdict (an id is reported
+ *    once);
+ *  - EVERY rubric criterion MUST be covered by the verdict (the agent cannot
+ *    silently skip a criterion to inflate the fraction).
+ *
+ * @param verdict - The host agent's per-criterion verdict.
+ * @param rubric - The item's authoritative MCP-supplied rubric.
+ * @returns The continuous score and its derived binary grade.
+ * @throws {Error} with a clear message when the verdict shape does not conform
+ *   to the rubric (per the rules above).
+ */
+export declare const scoreVerdict: (verdict: FreeFormVerdict, rubric: Rubric) => FreeFormGrade;
+//# sourceMappingURL=freeform.d.ts.map

package/dist/grading/freeform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freeform.d.ts","sourceRoot":"","sources":["../../src/grading/freeform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,YAAY,GACvB,SAAS,eAAe,EACxB,QAAQ,MAAM,KACb,aA0CF,CAAC"}

package/dist/grading/freeform.js

@@ -0,0 +1,85 @@
+/**
+ * @file PURE free-form grading (T048, FR-012/013, US-4).
+ *
+ * Scores a free-form item from the host agent's **per-criterion** verdict against
+ * the item's MCP-supplied {@link Rubric}. The score is the FRACTION of rubric
+ * criteria the agent marked `met`; the binary {@link Grade} is the projection of
+ * that score against the rubric's `passThreshold` (default
+ * {@link ASSESSMENT_CONFIG.freeFormPassThreshold} = 0.6) via the shared
+ * {@link toGrade} (one definition of "correct" across deterministic + free-form).
+ *
+ * Anti-gaming (critique E2, FR-013): the verdict MUST be a per-criterion array
+ * that aligns to the rubric's criteria ids. This module REJECTS a bare boolean,
+ * a missing/empty criteria array, an unknown criterion id, or a verdict that
+ * does not cover every rubric criterion — a lazy single self-pass is
+ * non-conformant and never silently scored. The host agent cannot invent its own
+ * criteria: only ids present in the authoritative rubric are accepted.
+ *
+ * Invariants (mirrors grading/deterministic.ts, engine/elo.ts):
+ *  - PURE: no `Date`, no `fs`, no `Math.random`, no network.
+ *  - The rubric is read-only input — never mutated here.
+ *  - Determinism: identical verdict + rubric ⇒ identical score + grade.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`submit_answer` free-form path), spec.md FR-012 / FR-013, research.md
+ * (OD-002 — free-form IN v1, `freeFormPassThreshold` 0.6), data-model.md
+ * (Grade = binary projection of a continuous score).
+ */
+import { ASSESSMENT_CONFIG } from "../config.js";
+import { toGrade } from "./deterministic.js";
+/**
+ * Score a free-form item from the host agent's per-criterion verdict (PURE).
+ *
+ * The score is `metCount / rubric.criteria.length` — the fraction of the
+ * authoritative rubric criteria the agent reported as met. The grade derives
+ * from that score against the rubric's `passThreshold` (falling back to
+ * {@link ASSESSMENT_CONFIG.freeFormPassThreshold} when the rubric omits one).
+ *
+ * The verdict is validated for SHAPE before scoring (anti-gaming, FR-013):
+ *  - it MUST carry a non-empty `criteria` array (a bare boolean / missing
+ *    criteria is rejected — the SDK union also rejects it, this is defence in
+ *    depth so a direct caller can't bypass the structure);
+ *  - every verdict criterion id MUST reference a real rubric criterion id (the
+ *    agent cannot invent criteria);
+ *  - no rubric criterion id may be duplicated in the verdict (an id is reported
+ *    once);
+ *  - EVERY rubric criterion MUST be covered by the verdict (the agent cannot
+ *    silently skip a criterion to inflate the fraction).
+ *
+ * @param verdict - The host agent's per-criterion verdict.
+ * @param rubric - The item's authoritative MCP-supplied rubric.
+ * @returns The continuous score and its derived binary grade.
+ * @throws {Error} with a clear message when the verdict shape does not conform
+ *   to the rubric (per the rules above).
+ */
+export const scoreVerdict = (verdict, rubric) => {
+    const rubricIds = new Set(rubric.criteria.map((c) => c.id));
+    // A bare boolean / missing criteria — defence in depth beyond the SDK union.
+    if (!Array.isArray(verdict.criteria) || verdict.criteria.length === 0) {
+        throw new Error("scoreVerdict: free-form verdict must be a per-criterion array " +
+            "(a bare boolean or empty verdict is non-conformant — FR-013)");
+    }
+    const seen = new Set();
+    for (const c of verdict.criteria) {
+        if (!rubricIds.has(c.id)) {
+            throw new Error(`scoreVerdict: verdict references unknown criterion id ${JSON.stringify(c.id)}; ` +
+                `the host agent may only judge the MCP-supplied rubric criteria ` +
+                `${JSON.stringify([...rubricIds])}`);
+        }
+        if (seen.has(c.id)) {
+            throw new Error(`scoreVerdict: verdict reports criterion id ${JSON.stringify(c.id)} more than once`);
+        }
+        seen.add(c.id);
+    }
+    // Every rubric criterion must be judged — no silent omissions.
+    if (seen.size !== rubricIds.size) {
+        const missing = [...rubricIds].filter((id) => !seen.has(id));
+        throw new Error(`scoreVerdict: verdict does not cover every rubric criterion; missing ` +
+            `${JSON.stringify(missing)} (a partial verdict is non-conformant — FR-013)`);
+    }
+    const metCount = verdict.criteria.filter((c) => c.met).length;
+    const score = metCount / rubric.criteria.length;
+    const passThreshold = rubric.passThreshold ?? ASSESSMENT_CONFIG.freeFormPassThreshold;
+    return { score, grade: toGrade(score, passThreshold) };
+};
+//# sourceMappingURL=freeform.js.map

package/dist/grading/freeform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freeform.js","sourceRoot":"","sources":["../../src/grading/freeform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAa7C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,OAAwB,EACxB,MAAc,EACC,EAAE;IACjB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5D,6EAA6E;IAC7E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,gEAAgE;YAC9D,8DAA8D,CACjE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACjC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,yDAAyD,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI;gBAC/E,iEAAiE;gBACjE,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CACtC,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,8CAA8C,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,iBAAiB,CACpF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,+DAA+D;IAC/D,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,uEAAuE;YACrE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,iDAAiD,CAC9E,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9D,MAAM,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;IAChD,MAAM,aAAa,GACjB,MAAM,CAAC,aAAa,IAAI,iBAAiB,CAAC,qBAAqB,CAAC;IAClE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,aAAa,CAAC,EAAE,CAAC;AACzD,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file vibe-hero MCP server entry point (T020).
+ *
+ * Bootstraps a stdio MCP server (`@modelcontextprotocol/sdk`) named `vibe-hero`
+ * with a `tools` capability, then registers all 10 tools from
+ * {@link TOOL_REGISTRY}. Each tool's handler is wrapped with the first-run setup
+ * gate (T021, {@link withSetupGate}) and adapted from its plain-JSON result into
+ * the SDK's `CallToolResult` shape ({@link toCallToolResult}).
+ *
+ * The SDK idiom (sdk 1.29.0): construct {@link McpServer}, then call
+ * `registerTool(name, { description, inputSchema }, cb)`. `registerTool` expects
+ * `inputSchema` as a *raw Zod shape* (`Record<string, ZodType>`), so we pass the
+ * registry's `inputSchema.shape` and the SDK hands the callback the parsed,
+ * validated args. Transport is {@link StdioServerTransport}.
+ *
+ * Importing this module never starts the server; only running it as the process
+ * entrypoint does (see the `import.meta.url` guard at the bottom), so tests can
+ * import {@link createServer} freely.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md, plan.md.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type AnyToolModule } from "./tools/types.js";
+/** Server name advertised to MCP hosts. Matches the product/skill namespace. */
+export declare const SERVER_NAME = "vibe-hero";
+/** Server version advertised to MCP hosts. */
+export declare const SERVER_VERSION = "0.1.0";
+/**
+ * Register one tool module on an {@link McpServer}, gating its handler and
+ * adapting the JSON result to a `CallToolResult`. Pulled out so both production
+ * and tests register tools the same way; `dirOverride` flows to the gate's
+ * profile lookup as a test seam.
+ *
+ * @param server - The MCP server to register onto.
+ * @param tool - The tool module from {@link TOOL_REGISTRY}.
+ * @param dirOverride - Profile-directory override (test seam) for the gate.
+ */
+export declare const registerToolModule: (server: McpServer, tool: AnyToolModule, dirOverride?: string) => void;
+/**
+ * Construct the vibe-hero MCP server with all tools registered (gated). Does not
+ * connect a transport — call {@link main} (or wire your own transport) to start.
+ *
+ * @param dirOverride - Profile-directory override (test seam) for the gate.
+ * @returns A configured, not-yet-connected {@link McpServer}.
+ */
+export declare const createServer: (dirOverride?: string) => McpServer;
+/**
+ * Start the server over stdio. Connects a {@link StdioServerTransport} and
+ * resolves once connected; the process then stays alive serving tool calls.
+ */
+export declare const main: () => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAExE,gFAAgF;AAChF,eAAO,MAAM,WAAW,cAAc,CAAC;AAEvC,8CAA8C;AAC9C,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,EACjB,MAAM,aAAa,EACnB,cAAc,MAAM,KACnB,IAWF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,cAAc,MAAM,KAAG,SASnD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,IAAI,QAAa,OAAO,CAAC,IAAI,CAIzC,CAAC"}