open-classify 0.1.1 → 0.2.0

package/dist/src/stock-validation.d.ts

@@ -1,4 +1,4 @@
-import type { JsonClassifierManifest, SafetySignal, ClassifierOutput } from "./stock.js";
+import type { JsonClassifierManifest, ClassifierOutput } from "./stock.js";
 export declare const STOCK_REASON_MAX_CHARS = 120;
 export declare const STOCK_REPLY_MAX_CHARS = 200;
 export declare const STOCK_TOOL_ID_MAX_CHARS = 64;
@@ -19,4 +19,3 @@ export interface LegacyValidateOptions {
     readonly manifest: JsonClassifierManifest;
 }
 export declare function validateClassifierOutputWithManifest(value: unknown, options: LegacyValidateOptions): ClassifierOutput;
-export type { SafetySignal };

package/dist/src/stock-validation.js

@@ -1,7 +1,7 @@
-import { DOWNSTREAM_MODEL_TIER_VALUES, MODEL_SPECIALIZATION_VALUES, SECURITY_DECISION_VALUES, } from "./enums.js";
+import { DOWNSTREAM_MODEL_TIER_VALUES, MODEL_SPECIALIZATION_VALUES, } from "./enums.js";
 import { Ajv } from "ajv/dist/ajv.js";
-import { STOCK_CLASSIFIER_NAMES } from "./stock.js";
-import { ensureNoDuplicates, isRecord, requireConfidence, requireEnum, requireNonEmptyStringMaxLength, requireNonNegativeSafeInteger, requireString, requireStringArray, throwInvalid, } from "./validation.js";
+import { CERTAINTY_VALUES, STOCK_CLASSIFIER_NAMES } from "./stock.js";
+import { ensureNoDuplicates, isRecord, requireEnum, requireNonEmptyStringMaxLength, requireNonNegativeSafeInteger, requireString, requireStringArray, throwInvalid, } from "./validation.js";
 export const STOCK_REASON_MAX_CHARS = 120;
 export const STOCK_REPLY_MAX_CHARS = 200;
 export const STOCK_TOOL_ID_MAX_CHARS = 64;
@@ -9,7 +9,7 @@ export const STOCK_TOOL_DESCRIPTION_MAX_CHARS = 240;
 export const STOCK_MANIFEST_NAME_MAX_CHARS = 80;
 export const STOCK_MANIFEST_VERSION_MAX_CHARS = 40;
 export const STOCK_MANIFEST_PURPOSE_MAX_CHARS = 400;
-const STOCK_SAFETY_RISK_LEVEL_VALUES = [
+const STOCK_PROMPT_INJECTION_RISK_LEVEL_VALUES = [
     "normal",
     "suspicious",
     "high_risk",
@@ -113,8 +113,8 @@ function validateStockOutputForName(name, value, model, tools) {
             return validateModelSpecializationOutput(value, model);
         case "tools":
             return validateToolsOutput(value, model, tools?.map((tool) => tool.id));
-        case "security":
-            return validateSecurityOutput(value, model);
+        case "prompt_injection":
+            return validatePromptInjectionOutput(value, model);
         default: {
             const _exhaustive = name;
             void _exhaustive;
@@ -123,17 +123,19 @@ function validateStockOutputForName(name, value, model, tools) {
     }
 }
 function validateMetadata(value, classifier, model) {
+    if (value.reason === undefined) {
+        throwInvalid(classifier, model, "reason is required");
+    }
+    if (value.certainty === undefined) {
+        throwInvalid(classifier, model, "certainty is required");
+    }
     return {
-        ...(value.reason === undefined
-            ? {}
-            : { reason: truncateText(requireString(value.reason, classifier, model, "reason"), STOCK_REASON_MAX_CHARS) }),
-        ...(value.confidence === undefined
-            ? {}
-            : { confidence: requireConfidence(value.confidence, classifier, model) }),
+        reason: truncateText(requireString(value.reason, classifier, model, "reason"), STOCK_REASON_MAX_CHARS),
+        certainty: requireEnum(value.certainty, CERTAINTY_VALUES, classifier, model, "certainty"),
     };
 }
 function validatePreflightOutput(value, model) {
-    ensureAllowedObjectKeys(value, ["reason", "confidence", "final_reply", "ack_reply"], "preflight", model, "output");
+    ensureAllowedObjectKeys(value, ["reason", "certainty", "final_reply", "ack_reply"], "preflight", model, "output");
     if (value.final_reply !== undefined && value.ack_reply !== undefined) {
         throwInvalid("preflight", model, "final_reply and ack_reply are mutually exclusive");
     }
@@ -163,7 +165,7 @@ function validateReplySignal(value, classifier, model, field) {
     return { reply };
 }
 function validateTierRoutingOutput(value, model) {
-    ensureAllowedObjectKeys(value, ["reason", "confidence", "model_tier"], "routing", model, "output");
+    ensureAllowedObjectKeys(value, ["reason", "certainty", "model_tier"], "routing", model, "output");
     const meta = validateMetadata(value, "routing", model);
     const modelTier = normalizeOptionalEnumValue(value.model_tier);
     return {
@@ -174,7 +176,7 @@ function validateTierRoutingOutput(value, model) {
     };
 }
 function validateModelSpecializationOutput(value, model) {
-    ensureAllowedObjectKeys(value, ["reason", "confidence", "specialization"], "model_specialization", model, "output");
+    ensureAllowedObjectKeys(value, ["reason", "certainty", "specialization"], "model_specialization", model, "output");
     const meta = validateMetadata(value, "model_specialization", model);
     const specialization = normalizeOptionalEnumValue(value.specialization);
     return {
@@ -194,7 +196,7 @@ function normalizeOptionalEnumValue(value) {
     return value;
 }
 function validateToolsOutput(value, model, configuredTools) {
-    ensureAllowedObjectKeys(value, ["reason", "confidence", "tools"], "tools", model, "output");
+    ensureAllowedObjectKeys(value, ["reason", "certainty", "tools"], "tools", model, "output");
     const meta = validateMetadata(value, "tools", model);
     const tools = requireStringArray(value.tools, "tools", model, "tools").map(normalizeTool);
     ensureNoDuplicates(tools, "tools", model, "tools");
@@ -208,39 +210,20 @@ function validateToolsOutput(value, model, configuredTools) {
     }
     return { ...meta, tools };
 }
-function validateSecurityOutput(value, model) {
-    ensureAllowedObjectKeys(value, ["reason", "confidence", "decision", "risk_level", "signals"], "security", model, "output");
-    const meta = validateMetadata(value, "security", model);
-    const decision = value.decision === undefined
-        ? undefined
-        : requireEnum(value.decision, SECURITY_DECISION_VALUES, "security", model, "decision");
-    const riskLevel = requireEnum(value.risk_level, STOCK_SAFETY_RISK_LEVEL_VALUES, "security", model, "risk_level");
-    const signals = requireStringArray(value.signals, "security", model, "signals");
-    ensureNoDuplicates(signals, "security", model, "signals");
-    if ((riskLevel === "normal" || riskLevel === "unknown") && signals.length > 0) {
-        throwInvalid("security", model, `${riskLevel} risk_level must not include signals`);
-    }
-    if (riskLevel !== "normal" && riskLevel !== "unknown" && signals.length === 0) {
-        throwInvalid("security", model, "elevated risk_level must include at least one signal");
-    }
-    if (decision === "block" && riskLevel !== "high_risk") {
-        throwInvalid("security", model, "decision block requires high_risk risk_level");
-    }
-    if (decision === "allow" && riskLevel === "high_risk") {
-        throwInvalid("security", model, "decision allow must not use high_risk risk_level");
-    }
+function validatePromptInjectionOutput(value, model) {
+    ensureAllowedObjectKeys(value, ["reason", "certainty", "risk_level"], "prompt_injection", model, "output");
+    const meta = validateMetadata(value, "prompt_injection", model);
+    const riskLevel = requireEnum(value.risk_level, STOCK_PROMPT_INJECTION_RISK_LEVEL_VALUES, "prompt_injection", model, "risk_level");
     return {
         ...meta,
-        ...(decision === undefined ? {} : { decision }),
         risk_level: riskLevel,
-        signals,
     };
 }
 function validateCustomOutput(value, classifier, model, schema) {
     if (!isRecord(value)) {
         throwInvalid(classifier, model, "output must be a JSON object");
     }
-    ensureAllowedObjectKeys(value, ["reason", "confidence", "output"], classifier, model, "output");
+    ensureAllowedObjectKeys(value, ["reason", "certainty", "output"], classifier, model, "output");
     if (value.output === undefined) {
         throwInvalid(classifier, model, "output is required for custom classifiers");
     }

package/dist/src/stock.d.ts

@@ -1,4 +1,4 @@
-import type { DownstreamModelTier, ModelSpecialization, SecurityDecision } from "./enums.js";
+import type { DownstreamModelTier, ModelSpecialization } from "./enums.js";
 export interface StockClassifierMessageInput {
     readonly role: "user" | "assistant";
     readonly text: string;
@@ -25,14 +25,15 @@ export interface SpecializationSignal {
 export interface ToolsSignal {
     readonly tools: ReadonlyArray<string>;
 }
-export interface SafetySignal {
-    readonly decision?: SecurityDecision;
+export interface PromptInjectionSignal {
     readonly risk_level: "normal" | "suspicious" | "high_risk" | "unknown";
-    readonly signals: ReadonlyArray<string>;
 }
+export type Certainty = "no_signal" | "very_weak" | "weak" | "tentative" | "reasonable" | "strong" | "very_strong" | "near_certain";
+export declare const CERTAINTY_VALUES: readonly ["no_signal", "very_weak", "weak", "tentative", "reasonable", "strong", "very_strong", "near_certain"];
+export declare const certaintyScore: Record<Certainty, number>;
 export interface ClassifierOutputMetadata {
-    readonly reason?: string;
-    readonly confidence?: number;
+    readonly reason: string;
+    readonly certainty: Certainty;
 }
 export interface PreflightClassifierOutput extends ClassifierOutputMetadata {
     readonly final_reply?: FinalReplySignal;
@@ -41,7 +42,7 @@ export interface PreflightClassifierOutput extends ClassifierOutputMetadata {
 export type RoutingClassifierOutput = TierSignal & ClassifierOutputMetadata;
 export type ModelSpecializationClassifierOutput = SpecializationSignal & ClassifierOutputMetadata;
 export type ToolsClassifierOutput = ToolsSignal & ClassifierOutputMetadata;
-export type SecurityClassifierOutput = SafetySignal & ClassifierOutputMetadata;
+export type PromptInjectionClassifierOutput = PromptInjectionSignal & ClassifierOutputMetadata;
 export interface CustomClassifierOutputValue extends ClassifierOutputMetadata {
     readonly output: unknown;
 }
@@ -50,9 +51,9 @@ export interface StockClassifierOutputs {
     readonly routing: RoutingClassifierOutput;
     readonly model_specialization: ModelSpecializationClassifierOutput;
     readonly tools: ToolsClassifierOutput;
-    readonly security: SecurityClassifierOutput;
+    readonly prompt_injection: PromptInjectionClassifierOutput;
 }
-export declare const STOCK_CLASSIFIER_NAMES: readonly ["preflight", "routing", "model_specialization", "tools", "security"];
+export declare const STOCK_CLASSIFIER_NAMES: readonly ["preflight", "routing", "model_specialization", "tools", "prompt_injection"];
 export type StockClassifierName = (typeof STOCK_CLASSIFIER_NAMES)[number];
 export type StockClassifierOutput = StockClassifierOutputs[StockClassifierName];
 export type ClassifierOutput = StockClassifierOutput | CustomClassifierOutputValue;
@@ -94,8 +95,8 @@ export declare function isStockManifest(manifest: RuntimeClassifierManifest): ma
 export declare function isCustomManifest(manifest: RuntimeClassifierManifest): manifest is RuntimeCustomManifest;
 export interface CustomClassifierOutput {
     readonly classifier: string;
-    readonly reason?: string;
-    readonly confidence?: number;
+    readonly reason: string;
+    readonly certainty: Certainty;
     readonly output: unknown;
 }
 export {};

package/dist/src/stock.js

@@ -1,9 +1,29 @@
+export const CERTAINTY_VALUES = [
+    "no_signal",
+    "very_weak",
+    "weak",
+    "tentative",
+    "reasonable",
+    "strong",
+    "very_strong",
+    "near_certain",
+];
+export const certaintyScore = {
+    no_signal: 0.00,
+    very_weak: 0.15,
+    weak: 0.30,
+    tentative: 0.45,
+    reasonable: 0.60,
+    strong: 0.75,
+    very_strong: 0.88,
+    near_certain: 0.97,
+};
 export const STOCK_CLASSIFIER_NAMES = [
     "preflight",
     "routing",
     "model_specialization",
     "tools",
-    "security",
+    "prompt_injection",
 ];
 // Helper: narrow a manifest to its stock kind for callers that know the name.
 export function isStockManifest(manifest) {

package/dist/src/ui-server.js

@@ -21,17 +21,17 @@ import { createServer } from "node:http";
 import { extname, join, normalize } from "node:path";
 import { loadCatalog } from "./catalog.js";
 import { CLASSIFIER_NAMES, REGISTRY } from "./classifiers.js";
+import { DEFAULT_CERTAINTY_THRESHOLD, certaintyThreshold, } from "./aggregator.js";
 import { classifierModelsFromConfig, loadOpenClassifyConfig, } from "./config.js";
-import { DOWNSTREAM_MODEL_TIER_VALUES, MODEL_SPECIALIZATION_VALUES, SECURITY_DECISION_VALUES, SECURITY_RISK_LEVEL_VALUES, SECURITY_SIGNAL_VALUES, } from "./enums.js";
+import { DEFAULT_CERTAINTY_GATE } from "./pipeline.js";
+import { DOWNSTREAM_MODEL_TIER_VALUES, MODEL_SPECIALIZATION_VALUES, PROMPT_INJECTION_RISK_LEVEL_VALUES, } from "./enums.js";
 import { createOllamaClassifierRunner, OLLAMA_CONTEXT_LENGTH, OLLAMA_DEFAULT_CATALOG_PATH, OLLAMA_MIN_AVAILABLE_MEMORY_BYTES, OLLAMA_MIN_TOTAL_MEMORY_BYTES, OLLAMA_REQUIRED_PARALLELISM, } from "./ollama.js";
 import { classifyOpenClassifyInput } from "./pipeline.js";
 // Served at GET /api/enums so the UI never needs to duplicate shared enum values.
 const CLASSIFIER_ENUMS = {
     downstream_model_tier: [...DOWNSTREAM_MODEL_TIER_VALUES],
     model_specialization: [...MODEL_SPECIALIZATION_VALUES],
-    security_decision: [...SECURITY_DECISION_VALUES],
-    security_risk_level: [...SECURITY_RISK_LEVEL_VALUES],
-    security_signal: [...SECURITY_SIGNAL_VALUES],
+    prompt_injection_risk_level: [...PROMPT_INJECTION_RISK_LEVEL_VALUES],
 };
 const CLASSIFIER_METADATA = REGISTRY.map((classifier) => ({
     name: classifier.name,
@@ -77,7 +77,13 @@ async function route(request, response) {
             return;
         }
         if (request.method === "GET" && url.pathname === "/api/classifiers") {
-            sendJson(response, { classifiers: CLASSIFIER_METADATA });
+            sendJson(response, {
+                classifiers: CLASSIFIER_METADATA,
+                aggregator: {
+                    certaintyGate: OPEN_CLASSIFY_CONFIG?.aggregator?.certaintyGate ?? DEFAULT_CERTAINTY_GATE,
+                    certaintyThreshold: certaintyThreshold(OPEN_CLASSIFY_CONFIG?.aggregator) ?? DEFAULT_CERTAINTY_THRESHOLD,
+                },
+            });
             return;
         }
         if (request.method === "GET") {
@@ -181,6 +187,7 @@ async function classifyStream(request, response) {
         const result = await classifyOpenClassifyInput(input, {
             runClassifier,
             catalog: loadCatalog(CATALOG_PATH),
+            aggregator: OPEN_CLASSIFY_CONFIG?.aggregator,
             signal: clientAbortController.signal,
         });
         send("pipeline_completed", result);

package/dist/src/validation.d.ts

@@ -11,7 +11,6 @@ export declare function requireStringArray(value: unknown, classifier: string, m
 export declare function requireStringMaxLength(value: unknown, classifier: string, model: string, path: string, maxChars: number): string;
 export declare function requireNonEmptyStringMaxLength(value: unknown, classifier: string, model: string, path: string, maxChars: number): string;
 export declare function requireEnum<const Values extends readonly string[]>(value: unknown, values: Values, classifier: string, model: string, path: string): Values[number];
-export declare function requireConfidence(value: unknown, classifier: string, model: string, path?: string): number;
 export declare function ensureExactKeys(value: Record<string, unknown>, keys: readonly string[], classifier: string, model: string): void;
 export declare function ensureNoDuplicates(values: string[], classifier: string, model: string, path: string): void;
 export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/src/validation.js

@@ -67,43 +67,6 @@ export function requireEnum(value, values, classifier, model, path) {
     }
     return value;
 }
-// `confidence` must be a finite number in [0, 1]. Required on every
-// classifier output (ClassifierResultBase); fallback shapes use 0.
-export function requireConfidence(value, classifier, model, path = "confidence") {
-    const confidence = normalizeConfidence(value);
-    if (typeof confidence !== "number" ||
-        !Number.isFinite(confidence) ||
-        confidence < 0 ||
-        confidence > 1) {
-        throwInvalid(classifier, model, `${path} must be a number between 0 and 1 inclusive`);
-    }
-    return confidence;
-}
-function normalizeConfidence(value) {
-    if (typeof value === "number") {
-        return value > 1 && value <= 100 ? value / 100 : value;
-    }
-    if (typeof value !== "string")
-        return value;
-    const text = value.trim().toLowerCase();
-    if (text === "")
-        return value;
-    if (text.endsWith("%")) {
-        const percent = Number(text.slice(0, -1).trim());
-        return Number.isFinite(percent) ? percent / 100 : value;
-    }
-    const numeric = Number(text);
-    if (Number.isFinite(numeric)) {
-        return numeric > 1 && numeric <= 100 ? numeric / 100 : numeric;
-    }
-    if (text === "high")
-        return 0.9;
-    if (text === "medium")
-        return 0.5;
-    if (text === "low")
-        return 0.2;
-    return value;
-}
 export function ensureExactKeys(value, keys, classifier, model) {
     const expected = new Set(keys);
     for (const key of Object.keys(value)) {

package/docs/adding-a-classifier.md

@@ -0,0 +1,132 @@
+# Adding a classifier
+
+Most additions are custom classifiers. You drop two files in a directory; the runtime picks them up. No TypeScript registry edits required.
+
+## 1. Pick a directory
+
+Custom classifier:
+
+```
+src/classifiers/custom/<name>/
+├── manifest.json
+└── prompt.md
+```
+
+Stock classifier names are closed (`preflight`, `routing`, `model_specialization`, `tools`, `prompt_injection`). You generally don't add new stock classifiers — extend behavior with a custom one instead.
+
+## 2. Write the manifest
+
+```json
+{
+  "kind": "custom",
+  "name": "topic_tags",
+  "version": "1.0.0",
+  "purpose": "Tag the message with a small set of topic labels for analytics.",
+  "order": 70,
+  "fallback": {
+    "reason": "Classifier failed; no tags generated.",
+    "certainty": "no_signal",
+    "output": { "tags": [] }
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["tags"],
+    "properties": {
+      "tags": {
+        "type": "array", "maxItems": 5,
+        "items": { "type": "string", "minLength": 1, "maxLength": 40 }
+      }
+    }
+  }
+}
+```
+
+Rules:
+
+- `name` must match the directory name.
+- `name` must not collide with a stock classifier name.
+- `order` must not collide with any other classifier.
+- `fallback` must validate against your `output_schema`.
+
+See [manifests.md](manifests.md) for the full field list.
+
+## 3. Write the prompt
+
+`prompt.md` is the classifier-specific instruction text. The runtime composes it with an auto-generated preamble that describes the JSON output envelope, so your prompt can focus on the classification rule:
+
+```markdown
+You are the topic_tags classifier.
+
+Tags are short single-word topic labels (lowercase, no spaces). Use at most five.
+Return an empty array when no clear topic applies.
+Do not invent tags for vague or ambiguous messages.
+```
+
+Keep it focused. Don't put aggregation or routing rules in prompts — those live in the runtime and catalog.
+
+## 4. Build and test
+
+```sh
+npm run build   # validates the manifest, sorts the registry, copies assets
+npm test
+```
+
+If the manifest is malformed, the loader throws `ClassifierManifestError` with the path and a specific reason.
+
+## 5. Consume the output
+
+```ts
+const classify = createClassifier({ catalog });
+const result = await classify(input);
+if (result.action === "route") {
+  const tags = result.classifier_outputs.topic_tags?.tags ?? [];
+}
+```
+
+`result.audit.custom_outputs[]` carries the same data with required `reason` and `certainty` metadata if you need to inspect them.
+
+## Choosing the classifier model
+
+For apps and OSS installs, prefer `open-classify.config.json`:
+
+```json
+{
+  "runner": {
+    "provider": "ollama",
+    "defaultModel": "gemma4:e4b-it-q4_K_M",
+    "models": {
+      "custom": {
+        "topic_tags": "qwen2.5:7b-instruct-q4_K_M"
+      }
+    }
+  }
+}
+```
+
+`runner.defaultModel` applies to every classifier without an override. `runner.models.stock` contains built-in classifier ids; `runner.models.custom` contains custom classifier ids.
+
+Classifier manifests may also carry an Ollama hint for packaged classifiers:
+
+```json
+{
+  "backend": { "ollama": { "base_model": "qwen2.5:7b-instruct-q4_K_M" } }
+}
+```
+
+Config file and function options take precedence over manifest hints.
+
+## Replacing the backend
+
+For full backend control, implement your own `RunClassifier` and pass it to `classifyOpenClassifyInput`:
+
+```ts
+import { classifyOpenClassifyInput, loadCatalog } from "open-classify";
+
+const runClassifier: RunClassifier = async (name, input, signal) => {
+  // call OpenAI, Anthropic, a remote service, etc.
+  // return a ClassifierOutput matching the classifier's contract.
+};
+
+await classifyOpenClassifyInput(input, { runClassifier, catalog: loadCatalog(...) });
+```

package/docs/manifests.md

@@ -0,0 +1,127 @@
+# Manifest reference
+
+Every classifier directory contains a `manifest.json`. Custom classifiers also contain a `prompt.md`. Stock prompt markdown lives in `src/classifiers/stock/prompts/` and is assembled at runtime.
+
+## Layout
+
+```
+src/classifiers/
+  stock/prompts/              # built-in prompt markdown
+    base.md
+    confidence.md
+    reason.md
+    tier.md
+    specialty.md
+    tools-output.md
+    tools.md
+  stock/<name>/                # built-in classifier
+    manifest.json
+  custom/<name>/               # caller-defined classifier
+    manifest.json
+    prompt.md
+```
+
+The `kind` field in the manifest must match the parent directory (`stock` or `custom`). Mismatches are rejected at load time.
+
+## Common fields
+
+| Field | Required | Description |
+|---|---|---|
+| `kind` | yes | `"stock"` or `"custom"` |
+| `name` | yes | Classifier id. Must match the directory name. |
+| `version` | yes | Contract version surfaced in `meta.classifiers[name].version`. |
+| `purpose` | yes | Human-readable description. |
+| `order` | yes | Integer sort key. Duplicate orders are rejected. |
+| `fallback` | yes | Output emitted when the classifier errors or times out. Must validate against the kind's output contract. |
+| `backend.ollama.base_model` | no | Packaged Ollama model hint for this classifier. User config and function options take precedence. |
+
+## Stock manifests
+
+Stock manifests use a closed set of names (`preflight`, `routing`, `model_specialization`, `tools`, `prompt_injection`). The runtime knows each name's signal type, so there's no `emits` field. Fallbacks must satisfy the signal contract for that name (see [signals.md](signals.md)).
+
+The `tools` classifier additionally takes:
+
+| Field | Required | Description |
+|---|---|---|
+| `tools` | no | Array of `{ id, description }`. Restricts which tool ids the classifier may emit. |
+
+Example (`src/classifiers/stock/prompt_injection/manifest.json`):
+
+```json
+{
+  "kind": "stock",
+  "name": "prompt_injection",
+  "version": "1.0.0",
+  "purpose": "Assess whether the target message contains prompt-injection attempts.",
+  "order": 50,
+  "fallback": {
+    "reason": "Classifier failed; prompt-injection risk is unknown.",
+    "certainty": "no_signal",
+    "risk_level": "unknown"
+  }
+}
+```
+
+## Custom manifests
+
+| Field | Required | Description |
+|---|---|---|
+| `output_schema` | yes | JSON Schema (Ajv-validated) for the `output` payload. |
+
+Custom classifier names must not collide with any stock classifier name.
+
+Example:
+
+```json
+{
+  "kind": "custom",
+  "name": "memory_retrieval_queries",
+  "version": "1.0.0",
+  "purpose": "Generate saved-memory query hints for caller-owned memory retrieval.",
+  "order": 60,
+  "fallback": {
+    "reason": "Classifier failed; no memory queries generated.",
+    "certainty": "no_signal",
+    "output": { "queries": [] }
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["queries"],
+    "properties": {
+      "queries": {
+        "type": "array", "maxItems": 5,
+        "items": { "type": "string", "minLength": 1, "maxLength": 120 }
+      }
+    }
+  }
+}
+```
+
+## Prompt files
+
+Stock prompt files live together in `src/classifiers/stock/prompts/`. The runtime assembles shared markdown (`base.md`, `reason.md`, `confidence.md`, `classifier-header.md`) with focused stock sections such as `tier.md`, `specialty.md`, `tools-output.md`, and the stock classifier file (`preflight.md`, `routing.md`, `model_specialization.md`, `tools.md`, or `prompt_injection.md`).
+
+Dynamic prompt sections use small markdown slots. For example, `tools.md` contains `{{allowed_tools}}`, and the runtime renders the allowed tool list from the tools manifest.
+
+Custom `prompt.md` is the classifier-specific instruction text. The runtime composes it with the shared JSON output envelope, so prompts can stay focused on classifier behavior:
+
+- what the classifier decides
+- when to emit each declared field
+- when to omit optional fields
+- short examples only when they clarify a boundary
+
+Do not put aggregation or model-id rules in prompts — those live in the runtime and catalog.
+
+## Validation rejections
+
+The loader rejects manifests that:
+
+- declare unsupported fields
+- collide on `name` or `order`
+- have an empty custom `prompt.md`
+- declare a custom name that matches a stock classifier
+- declare `kind` that doesn't match the parent directory
+- have a `fallback` that doesn't satisfy the signal or `output_schema`
+- are missing `output_schema` on a custom classifier
+- declare `tools` on any classifier other than the `tools` stock classifier