dsh-diagnostic-tutor 0.1.0

package/lib/types/trust-fence.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Browser trust fence for this plugin's HTTP surface.
+ *
+ * A bare `ctx.webServer.register()` route inherits **no authentication** — the
+ * framework does not wrap third-party routes, and its own gateway fence is
+ * package-internal. Every published plugin therefore re-implements the same
+ * behaviour, and so does this one.
+ *
+ * What it defends against: a page on another origin (or a DNS-rebound hostname)
+ * reaching these routes from the user's browser. The rule is that a request
+ * must arrive at a **loopback** host, from a **loopback** origin, and must not
+ * be marked cross-site.
+ *
+ * Deliberately a *behavioural* replica of
+ * `@deepseek-ai/dsh-client-connection`'s `api-request-trust.ts` /
+ * `loopback-hostname.ts`, not an import: those are not exported for third
+ * parties, and importing across a harness cohort is exactly what this project's
+ * cross-version discipline forbids.
+ *
+ * Anything that fails the fence gets 403 and no body, so a rejected caller
+ * learns nothing about what is behind it.
+ */
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
+/** The only part of a request the fence inspects. */
+export interface ApiTrustRequest {
+    headers: IncomingHttpHeaders;
+}
+/**
+ * Whether a hostname is this machine.
+ *
+ * `localhost`, IPv6 loopback, and any `127.0.0.0/8` address. Everything else —
+ * including a public name that resolves to 127.0.0.1 through DNS rebinding — is
+ * rejected, because the *name* is what an attacker controls.
+ *
+ * @param hostname - the hostname from a Host or Origin header.
+ * @returns whether it denotes the local machine.
+ */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Whether a request may reach the plugin API.
+ *
+ * @param request - the incoming request (only `headers` is read).
+ * @returns whether the request is same-origin and local.
+ */
+export declare function isTrustedApiRequest(request: ApiTrustRequest): boolean;
+/**
+ * Wrap a handler so it only runs for trusted requests.
+ *
+ * @param handler - the route body.
+ * @returns a handler that answers 403 without a body when the fence rejects.
+ */
+export declare function guarded(handler: (req: IncomingMessage, res: ServerResponse) => Promise<void> | void): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+//# sourceMappingURL=trust-fence.d.ts.map

package/lib/types/trust-fence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-fence.d.ts","sourceRoot":"","sources":["../../src/trust-fence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAErF,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,mBAAmB,CAAA;CAC7B;AAOD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQ5D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CA+BrE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAC3E,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAU9D"}

package/lib/types/udt.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Detection of the Universal Diagnostic Tutor skill.
+ *
+ * This module answers one question — "is the teaching brain present in this
+ * environment, and does it look like the one we mirror?" — and nothing else.
+ *
+ * How detection works, and what it deliberately avoids:
+ *   - it asks the **skill registry** (`ctx.skills`), the platform's own
+ *     discovery service, rather than looking at the filesystem. No path is
+ *     hardcoded and no skill root is assumed;
+ *   - it never copies, vendors or imports the skill's logic;
+ *   - it never constructs a DSH runtime object; the registry arrives from `ctx`;
+ *   - if anything is missing it returns an unavailable status with a reason
+ *     instead of throwing, so a profile without the skill degrades rather than
+ *     crashes.
+ *
+ * **Leakage rule.** `path` and `fingerprint` exist for the plugin's own
+ * diagnostics and for a future state panel. They must never reach
+ * learner-facing text: the skill's own protocol forbids naming its files,
+ * versions or repository in a tutoring reply, and this runtime will not be the
+ * thing that leaks them. Detection results are logged at `debug` and are
+ * deliberately absent from every tool's output schema.
+ */
+import type { SkillRegistry } from '@deepseek-ai/dsh-skill';
+/** The skill's canonical name, as declared in its frontmatter. */
+export declare const UDT_SKILL_NAME = "universal-diagnostic-tutor";
+/** How much we were able to verify about the detected skill. */
+export declare const UDT_COMPATIBILITIES: readonly ["compatible", "unknown", "unavailable"];
+export type UdtCompatibility = (typeof UDT_COMPATIBILITIES)[number];
+export interface UdtSkillStatus {
+    /** Whether the skill was found in the catalog. */
+    readonly available: boolean;
+    /**
+     * Whether the catalog could be read well enough to conclude anything.
+     *
+     * `false` means the skill was not found **in a catalog that demonstrably has
+     * entries**, so its absence is a real finding. `true` means entries were
+     * visible and the search was meaningful.
+     *
+     * This distinction exists because the registry's `list()` reads **the global
+     * layer alone** unless given a viewing `scope`, and the standard web profile
+     * mounts the filesystem skill provider inside a nested agent layer. From a
+     * plugin at the profile root the catalog is therefore *empty* even when the
+     * skill is installed and the tutor is using it — a miss that says nothing.
+     * Treating that as "not installed" produced a confident, wrong answer.
+     */
+    readonly catalogVisible: boolean;
+    /** The name we looked for. */
+    readonly name: string;
+    readonly compatibility: UdtCompatibility;
+    /** Discovery source label reported by the registry (provider-specific). */
+    readonly source?: string;
+    /** Owning provider's name. */
+    readonly provider?: string;
+    /** Directory the skill was loaded from. INTERNAL — never learner-facing. */
+    readonly path?: string;
+    /** Short content digest; a version hint that needs no version field. INTERNAL. */
+    readonly fingerprint?: string;
+    /** Why the status is what it is. Safe to log. */
+    readonly reason?: string;
+}
+/**
+ * Vocabulary that must appear in the skill body for us to call it compatible.
+ *
+ * The skill cannot declare a version — its maintenance contract permits only
+ * `name` and `description` in frontmatter — so compatibility is probed by
+ * *capability* instead: the terms this runtime mirrors must actually be there.
+ * That is more robust than a version string and needs no upstream change.
+ *
+ * These are deliberately few and structural: the Core Loop's `Diagnose` step
+ * and two ends of the seven-term status vocabulary.
+ */
+export declare const CAPABILITY_ANCHORS: readonly ["Diagnose", "unconfirmed", "blocked"];
+/** Stable short digest of a skill body, used as a version hint. */
+export declare function fingerprintContent(content: string): string;
+/**
+ * Detect the teaching brain.
+ *
+ * @param skills - the skill registry taken from `ctx`, or `undefined` when the
+ *   profile does not mount one.
+ * @returns the detection status; never throws.
+ */
+export declare function detectUdtSkill(skills: SkillRegistry | undefined): Promise<UdtSkillStatus>;
+/**
+ * Render a detection status as one log line.
+ *
+ * Kept here so the one place that knows about paths is also the one place that
+ * formats them, and so that callers cannot accidentally interpolate this into
+ * learner-facing text.
+ *
+ * @param status - the detection result.
+ * @returns a single line suitable for the harness log.
+ */
+export declare function describeUdtStatus(status: UdtSkillStatus): string;
+//# sourceMappingURL=udt.d.ts.map

package/lib/types/udt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"udt.d.ts","sourceRoot":"","sources":["../../src/udt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAE3D,kEAAkE;AAClE,eAAO,MAAM,cAAc,+BAA+B,CAAA;AAE1D,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,mDAAoD,CAAA;AACpF,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEnE,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,aAAa,EAAE,gBAAgB,CAAA;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,iDAAkD,CAAA;AAEjF,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAMD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAgF/F;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAKhE"}

package/lib/types/vocabulary.d.ts

@@ -0,0 +1,162 @@
+/**
+ * The closed vocabularies this runtime is allowed to speak.
+ *
+ * Every term below is **mirrored verbatim** from the Universal Diagnostic
+ * Tutor skill. None is invented here, and that is a hard rule rather than a
+ * preference: the skill's own mastery protocol says "The only concept-level
+ * status terms are these seven … never invent a second vocabulary."
+ *
+ * If a term needs to change, it changes in the skill first and is mirrored
+ * here second. Divergence would make the runtime and the teaching brain
+ * disagree about the same learner, which is the one failure this project
+ * cannot survive.
+ *
+ * Sources (skill `references/`):
+ *   - seven node states  -> `mastery_and_decision.md`
+ *   - six readiness gates -> `mastery_and_decision.md`
+ *   - teaching modes      -> `teaching_modes.md`
+ */
+import { z } from 'zod';
+/**
+ * The seven status terms, exactly as the skill defines them:
+ *
+ * | term        | meaning                                              |
+ * | ----------- | ---------------------------------------------------- |
+ * | unconfirmed | no evidence yet, even if related content was discussed |
+ * | explained   | the tutor explained it; mastery not proven            |
+ * | practiced   | the learner attempted at least one task               |
+ * | checked     | a check or near-transfer question was asked           |
+ * | weak        | partial understanding or unstable use                 |
+ * | blocked     | cannot proceed; a prerequisite is missing or misread  |
+ * | confirmed   | sound reasoning plus independent use or transfer      |
+ */
+export declare const NODE_STATES: readonly ["unconfirmed", "explained", "practiced", "checked", "weak", "blocked", "confirmed"];
+export declare const NodeStateSchema: z.ZodEnum<{
+    unconfirmed: "unconfirmed";
+    explained: "explained";
+    practiced: "practiced";
+    checked: "checked";
+    weak: "weak";
+    blocked: "blocked";
+    confirmed: "confirmed";
+}>;
+export type NodeState = z.infer<typeof NodeStateSchema>;
+/** The state a node is born in. Nothing is ever born confirmed. */
+export declare const INITIAL_NODE_STATE: NodeState;
+export declare const READINESS_OUTCOMES: readonly ["advance", "advance-with-caution", "review-first", "step-down", "diagnose-again", "more-practice"];
+export declare const ReadinessSchema: z.ZodEnum<{
+    advance: "advance";
+    "advance-with-caution": "advance-with-caution";
+    "review-first": "review-first";
+    "step-down": "step-down";
+    "diagnose-again": "diagnose-again";
+    "more-practice": "more-practice";
+}>;
+export type Readiness = z.infer<typeof ReadinessSchema>;
+/**
+ * What each readiness outcome means for *navigation*.
+ *
+ * The decision vocabulary is the skill's six readiness outcomes, reused as-is.
+ * Inventing a second set of words for "what happens next" would be exactly the
+ * duplication this project exists to avoid — and the six already say it: an
+ * outcome is a judgement about the current concept, and moving or staying is
+ * what that judgement implies.
+ *
+ * The runtime only needs to know one structural thing about each outcome:
+ * whether it names a different node to go to.
+ *
+ * | outcome                | target        | means                                  |
+ * | ---------------------- | ------------- | -------------------------------------- |
+ * | `advance`              | required      | move to that node                      |
+ * | `advance-with-caution` | required      | move, with an early check there         |
+ * | `step-down`            | required      | the blocker; usually a prerequisite     |
+ * | `review-first`         | optional      | go back to that node, or review here    |
+ * | `more-practice`        | forbidden     | stay here and practise                  |
+ * | `diagnose-again`       | forbidden     | stay here and ask a sharper question    |
+ */
+export type TargetRequirement = 'required' | 'optional' | 'forbidden';
+/**
+ * Whether an outcome must, may, or must not name a target node.
+ *
+ * @param action - one of the skill's readiness outcomes.
+ * @returns the structural requirement.
+ */
+export declare function targetRequirement(action: Readiness): TargetRequirement;
+/**
+ * Whether an outcome ends the current focus.
+ *
+ * Only a genuine move does. Staying keeps the focus active, because the learner
+ * is still working the same node — ending it there would make the panel claim
+ * they had moved on.
+ *
+ * @param action - one of the skill's readiness outcomes.
+ * @param hasTarget - whether a target node was named.
+ * @returns whether the focus should end.
+ */
+export declare function endsFocus(action: Readiness, hasTarget: boolean): boolean;
+export declare const TEACHING_MODES: readonly ["auto", "zero-base", "standard", "advanced"];
+export declare const TeachingModeSchema: z.ZodEnum<{
+    auto: "auto";
+    "zero-base": "zero-base";
+    standard: "standard";
+    advanced: "advanced";
+}>;
+export type TeachingMode = z.infer<typeof TeachingModeSchema>;
+/**
+ * How a node relates to its parent.
+ *
+ * These describe *diagnosis*, not a syllabus: `prerequisite` means "this was
+ * found to block that", not "week 2 comes after week 1". There is deliberately
+ * no `next-in-course` relation, because nothing in this runtime knows a
+ * teaching order — the skill decides that per session.
+ */
+export declare const NODE_RELATIONS: readonly ["goal", "part-of", "prerequisite", "related"];
+export declare const NodeRelationSchema: z.ZodEnum<{
+    goal: "goal";
+    "part-of": "part-of";
+    prerequisite: "prerequisite";
+    related: "related";
+}>;
+export type NodeRelation = z.infer<typeof NodeRelationSchema>;
+/**
+ * The kinds of evidence the runtime records.
+ *
+ * This list is intentionally about *observations*, not judgements: the runtime
+ * stores what happened, and never whether it was good.
+ */
+export declare const EVIDENCE_KINDS: readonly ["goal-stated", "diagnosis", "explanation", "practice", "check", "transfer"];
+export declare const EvidenceKindSchema: z.ZodEnum<{
+    "goal-stated": "goal-stated";
+    diagnosis: "diagnosis";
+    explanation: "explanation";
+    practice: "practice";
+    check: "check";
+    transfer: "transfer";
+}>;
+export type EvidenceKind = z.infer<typeof EvidenceKindSchema>;
+/**
+ * Evidence kinds strong enough to support `confirmed`.
+ *
+ * The skill is explicit that the weaker signals never confirm: "a correct
+ * answer is not proof of reasoning … explanation alone and one lucky answer
+ * never confirm readiness." So `explanation`, `practice` and the purely
+ * observational kinds cannot confirm a node, and the runtime refuses to let
+ * them — see `diagnosis.ts`.
+ *
+ * This is a structural floor, not a pedagogical verdict: clearing it makes
+ * `confirmed` *permissible*, and the skill still decides whether it is right.
+ */
+export declare const CONFIRMING_EVIDENCE_KINDS: readonly ["check", "transfer"];
+export type ConfirmingEvidenceKind = (typeof CONFIRMING_EVIDENCE_KINDS)[number];
+/** Whether an evidence kind may support `confirmed`. */
+export declare function isConfirmingEvidence(kind: EvidenceKind): kind is ConfirmingEvidenceKind;
+/**
+ * Field names that would turn learning state into a grade.
+ *
+ * The skill forbids it in prose ("Never turn mastery tracking into scores") and
+ * the zod schemas already strip unknown keys, so no such field can be stored.
+ * This list exists so the prohibition is asserted by tests rather than trusted
+ * to review.
+ */
+export declare const FORBIDDEN_SCORE_FIELDS: readonly ["score", "grade", "points", "percent", "percentage", "progress", "stars", "rating", "level", "xp"];
+//# sourceMappingURL=vocabulary.d.ts.map

package/lib/types/vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.d.ts","sourceRoot":"","sources":["../../src/vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAMvB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,+FAQd,CAAA;AACV,eAAO,MAAM,eAAe;;;;;;;;EAAsB,CAAA;AAClD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAEvD,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,EAAE,SAAyB,CAAA;AAM1D,eAAO,MAAM,kBAAkB,8GAOrB,CAAA;AACV,eAAO,MAAM,eAAe;;;;;;;EAA6B,CAAA;AACzD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,CAAA;AAWrE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAEtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAExE;AAMD,eAAO,MAAM,cAAc,wDAAyD,CAAA;AACpF,eAAO,MAAM,kBAAkB;;;;;EAAyB,CAAA;AACxD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAM7D;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,yDASjB,CAAA;AACV,eAAO,MAAM,kBAAkB;;;;;EAAyB,CAAA;AACxD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAM7D;;;;;GAKG;AACH,eAAO,MAAM,cAAc,uFAajB,CAAA;AACV,eAAO,MAAM,kBAAkB;;;;;;;EAAyB,CAAA;AACxD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAE7D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,gCAAiC,CAAA;AACvE,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE/E,wDAAwD;AACxD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,IAAI,sBAAsB,CAEvF;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,8GAWzB,CAAA"}

package/lib/udt.js

@@ -0,0 +1,141 @@
+/**
+ * Detection of the Universal Diagnostic Tutor skill.
+ *
+ * This module answers one question — "is the teaching brain present in this
+ * environment, and does it look like the one we mirror?" — and nothing else.
+ *
+ * How detection works, and what it deliberately avoids:
+ *   - it asks the **skill registry** (`ctx.skills`), the platform's own
+ *     discovery service, rather than looking at the filesystem. No path is
+ *     hardcoded and no skill root is assumed;
+ *   - it never copies, vendors or imports the skill's logic;
+ *   - it never constructs a DSH runtime object; the registry arrives from `ctx`;
+ *   - if anything is missing it returns an unavailable status with a reason
+ *     instead of throwing, so a profile without the skill degrades rather than
+ *     crashes.
+ *
+ * **Leakage rule.** `path` and `fingerprint` exist for the plugin's own
+ * diagnostics and for a future state panel. They must never reach
+ * learner-facing text: the skill's own protocol forbids naming its files,
+ * versions or repository in a tutoring reply, and this runtime will not be the
+ * thing that leaks them. Detection results are logged at `debug` and are
+ * deliberately absent from every tool's output schema.
+ */
+import { createHash } from 'node:crypto';
+/** The skill's canonical name, as declared in its frontmatter. */
+export const UDT_SKILL_NAME = 'universal-diagnostic-tutor';
+/** How much we were able to verify about the detected skill. */
+export const UDT_COMPATIBILITIES = ['compatible', 'unknown', 'unavailable'];
+/**
+ * Vocabulary that must appear in the skill body for us to call it compatible.
+ *
+ * The skill cannot declare a version — its maintenance contract permits only
+ * `name` and `description` in frontmatter — so compatibility is probed by
+ * *capability* instead: the terms this runtime mirrors must actually be there.
+ * That is more robust than a version string and needs no upstream change.
+ *
+ * These are deliberately few and structural: the Core Loop's `Diagnose` step
+ * and two ends of the seven-term status vocabulary.
+ */
+export const CAPABILITY_ANCHORS = ['Diagnose', 'unconfirmed', 'blocked'];
+/** Stable short digest of a skill body, used as a version hint. */
+export function fingerprintContent(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex').slice(0, 12);
+}
+function unavailable(name, reason, catalogVisible = false) {
+    return { available: false, name, compatibility: 'unavailable', reason, catalogVisible };
+}
+/**
+ * Detect the teaching brain.
+ *
+ * @param skills - the skill registry taken from `ctx`, or `undefined` when the
+ *   profile does not mount one.
+ * @returns the detection status; never throws.
+ */
+export async function detectUdtSkill(skills) {
+    if (!skills) {
+        return unavailable(UDT_SKILL_NAME, 'no skill catalog is mounted in this profile');
+    }
+    let summaries;
+    try {
+        summaries = await skills.list();
+    }
+    catch (error) {
+        return unavailable(UDT_SKILL_NAME, `skill discovery failed: ${error.message}`);
+    }
+    const summary = summaries.find((entry) => entry.name === UDT_SKILL_NAME);
+    if (!summary) {
+        // An empty catalog proves nothing: see `catalogVisible`. Report the miss
+        // either way, but only claim absence when entries were actually visible.
+        return summaries.length === 0
+            ? unavailable(UDT_SKILL_NAME, 'no skills are visible from this profile scope; the catalog is mounted per agent ' +
+                'in some profiles, so nothing can be concluded about what is installed', false)
+            : unavailable(UDT_SKILL_NAME, `not among the ${summaries.length} skills visible in this scope`, true);
+    }
+    const base = {
+        available: true,
+        catalogVisible: true,
+        name: UDT_SKILL_NAME,
+        source: summary.source,
+        provider: summary.provider,
+    };
+    // `list()` gives a cheap location via `resourceBase`; only a directory-based
+    // provider has a path at all, and a remote provider legitimately has none.
+    const listedPath = summary.resourceBase?.kind === 'directory' ? summary.resourceBase.path : undefined;
+    let definition;
+    try {
+        definition = await skills.get(UDT_SKILL_NAME);
+    }
+    catch (error) {
+        return {
+            ...base,
+            compatibility: 'unknown',
+            reason: `listed but its body could not be loaded: ${error.message}`,
+            ...(listedPath === undefined ? {} : { path: listedPath }),
+        };
+    }
+    if (!definition) {
+        return {
+            ...base,
+            compatibility: 'unknown',
+            reason: 'listed but its body could not be loaded',
+            ...(listedPath === undefined ? {} : { path: listedPath }),
+        };
+    }
+    const path = definition.path ?? listedPath;
+    const fingerprint = fingerprintContent(definition.content);
+    const missing = CAPABILITY_ANCHORS.filter((anchor) => !definition.content.includes(anchor));
+    if (missing.length > 0) {
+        return {
+            ...base,
+            compatibility: 'unknown',
+            fingerprint,
+            reason: `body is missing expected vocabulary: ${missing.join(', ')}`,
+            ...(path === undefined ? {} : { path }),
+        };
+    }
+    return {
+        ...base,
+        compatibility: 'compatible',
+        fingerprint,
+        ...(path === undefined ? {} : { path }),
+    };
+}
+/**
+ * Render a detection status as one log line.
+ *
+ * Kept here so the one place that knows about paths is also the one place that
+ * formats them, and so that callers cannot accidentally interpolate this into
+ * learner-facing text.
+ *
+ * @param status - the detection result.
+ * @returns a single line suitable for the harness log.
+ */
+export function describeUdtStatus(status) {
+    if (!status.available)
+        return `unavailable (${status.reason ?? 'unknown reason'})`;
+    const where = status.provider === undefined ? '' : ` via ${status.provider}`;
+    const digest = status.fingerprint === undefined ? '' : ` [${status.fingerprint}]`;
+    return `${status.compatibility}${where}${digest}`;
+}
+//# sourceMappingURL=udt.js.map

package/lib/udt.js.map

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

package/lib/vocabulary.js

@@ -0,0 +1,182 @@
+/**
+ * The closed vocabularies this runtime is allowed to speak.
+ *
+ * Every term below is **mirrored verbatim** from the Universal Diagnostic
+ * Tutor skill. None is invented here, and that is a hard rule rather than a
+ * preference: the skill's own mastery protocol says "The only concept-level
+ * status terms are these seven … never invent a second vocabulary."
+ *
+ * If a term needs to change, it changes in the skill first and is mirrored
+ * here second. Divergence would make the runtime and the teaching brain
+ * disagree about the same learner, which is the one failure this project
+ * cannot survive.
+ *
+ * Sources (skill `references/`):
+ *   - seven node states  -> `mastery_and_decision.md`
+ *   - six readiness gates -> `mastery_and_decision.md`
+ *   - teaching modes      -> `teaching_modes.md`
+ */
+import { z } from 'zod';
+/* -------------------------------------------------------------------------- */
+/* Node state — the skill's seven concept-level status terms                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * The seven status terms, exactly as the skill defines them:
+ *
+ * | term        | meaning                                              |
+ * | ----------- | ---------------------------------------------------- |
+ * | unconfirmed | no evidence yet, even if related content was discussed |
+ * | explained   | the tutor explained it; mastery not proven            |
+ * | practiced   | the learner attempted at least one task               |
+ * | checked     | a check or near-transfer question was asked           |
+ * | weak        | partial understanding or unstable use                 |
+ * | blocked     | cannot proceed; a prerequisite is missing or misread  |
+ * | confirmed   | sound reasoning plus independent use or transfer      |
+ */
+export const NODE_STATES = [
+    'unconfirmed',
+    'explained',
+    'practiced',
+    'checked',
+    'weak',
+    'blocked',
+    'confirmed',
+];
+export const NodeStateSchema = z.enum(NODE_STATES);
+/** The state a node is born in. Nothing is ever born confirmed. */
+export const INITIAL_NODE_STATE = 'unconfirmed';
+/* -------------------------------------------------------------------------- */
+/* Readiness — the skill's six outcomes of the readiness gate                 */
+/* -------------------------------------------------------------------------- */
+export const READINESS_OUTCOMES = [
+    'advance',
+    'advance-with-caution',
+    'review-first',
+    'step-down',
+    'diagnose-again',
+    'more-practice',
+];
+export const ReadinessSchema = z.enum(READINESS_OUTCOMES);
+const TARGET_REQUIREMENT = {
+    advance: 'required',
+    'advance-with-caution': 'required',
+    'step-down': 'required',
+    'review-first': 'optional',
+    'more-practice': 'forbidden',
+    'diagnose-again': 'forbidden',
+};
+/**
+ * Whether an outcome must, may, or must not name a target node.
+ *
+ * @param action - one of the skill's readiness outcomes.
+ * @returns the structural requirement.
+ */
+export function targetRequirement(action) {
+    return TARGET_REQUIREMENT[action];
+}
+/**
+ * Whether an outcome ends the current focus.
+ *
+ * Only a genuine move does. Staying keeps the focus active, because the learner
+ * is still working the same node — ending it there would make the panel claim
+ * they had moved on.
+ *
+ * @param action - one of the skill's readiness outcomes.
+ * @param hasTarget - whether a target node was named.
+ * @returns whether the focus should end.
+ */
+export function endsFocus(action, hasTarget) {
+    return targetRequirement(action) === 'required' || (action === 'review-first' && hasTarget);
+}
+/* -------------------------------------------------------------------------- */
+/* Teaching mode — the skill's four modes                                     */
+/* -------------------------------------------------------------------------- */
+export const TEACHING_MODES = ['auto', 'zero-base', 'standard', 'advanced'];
+export const TeachingModeSchema = z.enum(TEACHING_MODES);
+/* -------------------------------------------------------------------------- */
+/* Map relations — how a node attaches to the diagnosis map                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * How a node relates to its parent.
+ *
+ * These describe *diagnosis*, not a syllabus: `prerequisite` means "this was
+ * found to block that", not "week 2 comes after week 1". There is deliberately
+ * no `next-in-course` relation, because nothing in this runtime knows a
+ * teaching order — the skill decides that per session.
+ */
+export const NODE_RELATIONS = [
+    /** The single root node of a course: the goal itself, in the learner's words. */
+    'goal',
+    /** A component the goal decomposes into, revealed by diagnosis. */
+    'part-of',
+    /** Found to block its parent; must be resolved first. */
+    'prerequisite',
+    /** Associated knowledge that is neither a component nor a blocker. */
+    'related',
+];
+export const NodeRelationSchema = z.enum(NODE_RELATIONS);
+/* -------------------------------------------------------------------------- */
+/* Evidence — what a state change is allowed to rest on                       */
+/* -------------------------------------------------------------------------- */
+/**
+ * The kinds of evidence the runtime records.
+ *
+ * This list is intentionally about *observations*, not judgements: the runtime
+ * stores what happened, and never whether it was good.
+ */
+export const EVIDENCE_KINDS = [
+    /** The learner stated the goal themselves. */
+    'goal-stated',
+    /** A gap, prerequisite or blocker was identified. */
+    'diagnosis',
+    /** The learner explained something in their own words. */
+    'explanation',
+    /** The learner attempted a task. */
+    'practice',
+    /** A check or near-transfer question was asked and answered. */
+    'check',
+    /** Independent use or transfer was demonstrated. */
+    'transfer',
+];
+export const EvidenceKindSchema = z.enum(EVIDENCE_KINDS);
+/**
+ * Evidence kinds strong enough to support `confirmed`.
+ *
+ * The skill is explicit that the weaker signals never confirm: "a correct
+ * answer is not proof of reasoning … explanation alone and one lucky answer
+ * never confirm readiness." So `explanation`, `practice` and the purely
+ * observational kinds cannot confirm a node, and the runtime refuses to let
+ * them — see `diagnosis.ts`.
+ *
+ * This is a structural floor, not a pedagogical verdict: clearing it makes
+ * `confirmed` *permissible*, and the skill still decides whether it is right.
+ */
+export const CONFIRMING_EVIDENCE_KINDS = ['check', 'transfer'];
+/** Whether an evidence kind may support `confirmed`. */
+export function isConfirmingEvidence(kind) {
+    return CONFIRMING_EVIDENCE_KINDS.includes(kind);
+}
+/* -------------------------------------------------------------------------- */
+/* Things the runtime must never produce                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * Field names that would turn learning state into a grade.
+ *
+ * The skill forbids it in prose ("Never turn mastery tracking into scores") and
+ * the zod schemas already strip unknown keys, so no such field can be stored.
+ * This list exists so the prohibition is asserted by tests rather than trusted
+ * to review.
+ */
+export const FORBIDDEN_SCORE_FIELDS = [
+    'score',
+    'grade',
+    'points',
+    'percent',
+    'percentage',
+    'progress',
+    'stars',
+    'rating',
+    'level',
+    'xp',
+];
+//# sourceMappingURL=vocabulary.js.map

package/lib/vocabulary.js.map

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