@panaversity/ksor 0.0.29 → 0.0.30

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @panaversity/ksor
 
+## 0.0.30
+
+### Patch Changes
+
+- fbf149b: Quizzes, as governed attachments of a document.
+
+  A document in `knowledge/` may now carry `<doc>.quiz.yaml` beside its summary
+  and its flashcard deck. It renders at the end of the document's page, under the
+  deck: choose an option, see immediately whether you were right, and read the
+  explanation before moving on. There is no pass mark — a quiz here checks
+  understanding of the record, it does not certify anybody — and answers stay in
+  the reader's own browser.
+
+  A quiz is **part of its document, not a document**: no URL, no sidebar row, no
+  `llms.txt` line, no markdown twin, no search entry, and no stable id. That last
+  one settles a question worth being explicit about: because `ksor ingest` creates
+  no node for a quiz, **the answer key cannot reach the MCP surface at all**.
+  There is nothing for an agent to search and nothing for it to read — not by a
+  filter that could be forgotten, but because the row does not exist. Governance
+  inherits from the parent exactly as the summary and the deck already do.
+
+  **`pnpm check` and `pnpm build` refuse a quiz a reader could pass without
+  reading it**, naming the questions to fix:
+
+  - `ksor-quiz-answer-bias` — more than 60% of answers at one option position
+  - `ksor-quiz-length-bias` — picking the longest or shortest option usually wins
+  - `ksor-quiz-answer-run` — four or more questions in a row share an answer
+  - `ksor-quiz-contradiction` — an explanation calls the marked answer wrong
+  - `ksor-quiz-duplicate-stem` — two questions open with the same 60 characters
+
+  These are carried from the predecessor, where the same mistakes shipped and were
+  found by readers rather than by the project — one quiz put every correct answer
+  in the same position across 451 questions. There they lived in a script that was
+  run once; here they are part of loading the file, so a quiz that fails them
+  cannot be published. The ratio rules do not apply below five questions, where
+  enforcing a spread would mean choosing an author's answers for them.
+
+  `ksor init` ships a quiz on the seed document, so a first `pnpm dev` shows the
+  shape. Its own first draft was refused for putting four of five answers at
+  option B — the check catching exactly what it was carried for.
+
 ## 0.0.29
 
 ### Patch Changes

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-pl4aOpVs.mjs";
-import { A as runProbe$1, C as keyRingFromEnv, D as prewarmPool, E as pooledEndpointFor, F as withPgRetry$1, I as withProbeDeadline$1, L as z$1, M as storedTextSearchConfig, N as tlsPosture, O as readHandler, P as visibleTiers$1, S as embedQueryVlit, T as parseInstanceText$1, _ as buildShippedProvider$1, a as MAX_OUTLINE_LIMIT, b as contentPool$1, c as MissingProviderKeyError$1, d as READ_OUTPUT, f as SEARCH_OUTPUT, g as assertSchemaCompatible, h as assertGovernanceServable$1, i as GovernanceGateError$1, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, m as TextSearchConfigMismatch, n as EmbeddingSpaceMismatch$1, p as SchemaVersionError, r as FLOOR, s as McpServer$1, t as ContentStoreError$1, u as READ_ONLY, v as checkEmbeddingSpace$1, w as outlineHandler, x as contentPoolMin, y as composeInstructions } from "./gateway-api-8lNruq9e-CuohjtoK.mjs";
+import { A as runProbe$1, C as keyRingFromEnv, D as prewarmPool, E as pooledEndpointFor, F as withPgRetry$1, I as withProbeDeadline$1, L as z$1, M as storedTextSearchConfig, N as tlsPosture, O as readHandler, P as visibleTiers$1, S as embedQueryVlit, T as parseInstanceText$1, _ as buildShippedProvider$1, a as MAX_OUTLINE_LIMIT, b as contentPool$1, c as MissingProviderKeyError$1, d as READ_OUTPUT, f as SEARCH_OUTPUT, g as assertSchemaCompatible, h as assertGovernanceServable$1, i as GovernanceGateError$1, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, m as TextSearchConfigMismatch, n as EmbeddingSpaceMismatch$1, p as SchemaVersionError, r as FLOOR, s as McpServer$1, t as ContentStoreError$1, u as READ_ONLY, v as checkEmbeddingSpace$1, w as outlineHandler, x as contentPoolMin, y as composeInstructions } from "./gateway-api-CbFkHZiU-HvlJRjRB.mjs";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { InMemoryTransport, LATEST_PROTOCOL_VERSION, createMcpHandler } from "@modelcontextprotocol/server";
@@ -16,7 +16,7 @@ import { bodyLimit } from "hono/body-limit";
 import { execFileSync, spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
-//#region ../content-gateway/dist/main-C-OMrGGt.mjs
+//#region ../content-gateway/dist/main-CS5a_8OW.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -1583,7 +1583,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-DU1nqwZa.mjs
+//#region ../content/dist/commands-CLUS9CX8.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -4208,6 +4208,10 @@ const ATTACHMENT_SUFFIXES = [
 	{
 		suffix: ".flashcards.yaml",
 		kind: "deck"
+	},
+	{
+		suffix: ".quiz.yaml",
+		kind: "quiz"
 	}
 ];
 /**

package/dist/{gateway-api-8lNruq9e-CuohjtoK.mjs → gateway-api-CbFkHZiU-HvlJRjRB.mjs}

@@ -5,7 +5,7 @@ import { z, z as z$1 } from "zod";
 import pg from "pg";
 import path from "node:path";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-//#region ../content-gateway/dist/gateway-api-8lNruq9e.mjs
+//#region ../content-gateway/dist/gateway-api-CbFkHZiU.mjs
 /**
 * The record's system prompt: instance.md's body, preserved beneath a framework
 * floor. Lifted out of server.ts so the public gateway surface can re-export

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-8lNruq9e-CuohjtoK.mjs";
+import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-CbFkHZiU-HvlJRjRB.mjs";
 export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",

package/templates/scaffold/.agents/skills/format-checker/check.mjs

@@ -41,7 +41,7 @@ const ASSET_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".web
 // rules below. This mirrors packages/content/src/lib/attachment-rule.ts, which
 // this dependency-free file cannot import; ATTACHMENT_CASES there is the table
 // both are held to.
-const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml"];
+const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml", ".quiz.yaml"];
 // One character off a real attachment, refused BY NAME: `.yml` reaches the
 // site bundler's `Unknown file type` throw, which names the path and nothing
 // about the rule.
@@ -49,6 +49,8 @@ const ATTACHMENT_NEAR_MISSES = [
   [".flashcards.yml", ".flashcards.yaml"],
   [".flashcards.json", ".flashcards.yaml"],
   [".summary.markdown", ".summary.md"],
+  [".quiz.yml", ".quiz.yaml"],
+  [".quiz.json", ".quiz.yaml"],
 ];
 
 /** The attachment suffix this name carries, or null. A dotfile has no stem. */

package/templates/scaffold/.claude/skills/format-checker/check.mjs

@@ -41,7 +41,7 @@ const ASSET_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".web
 // rules below. This mirrors packages/content/src/lib/attachment-rule.ts, which
 // this dependency-free file cannot import; ATTACHMENT_CASES there is the table
 // both are held to.
-const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml"];
+const ATTACHMENT_SUFFIXES = [".summary.md", ".summary.mdx", ".flashcards.yaml", ".quiz.yaml"];
 // One character off a real attachment, refused BY NAME: `.yml` reaches the
 // site bundler's `Unknown file type` throw, which names the path and nothing
 // about the rule.
@@ -49,6 +49,8 @@ const ATTACHMENT_NEAR_MISSES = [
   [".flashcards.yml", ".flashcards.yaml"],
   [".flashcards.json", ".flashcards.yaml"],
   [".summary.markdown", ".summary.md"],
+  [".quiz.yml", ".quiz.yaml"],
+  [".quiz.json", ".quiz.yaml"],
 ];
 
 /** The attachment suffix this name carries, or null. A dotfile has no stem. */

package/templates/scaffold/AGENTS.md

@@ -506,11 +506,12 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   refused.
 - Images and assets live in `knowledge/` beside the document that uses them,
   referenced by relative links. A relative link must never leave `knowledge/`.
-- **Study attachments.** A document may carry two optional companions named
-  after it, in the same folder: `<doc>.summary.md` (a short précis) and
-  `<doc>.flashcards.yaml` (a recall deck). The summary appears as a second tab
-  beside the document's own words; the deck appears at the END of that
-  document's page. Both appear nowhere else in the site.
+- **Study attachments.** A document may carry three optional companions named
+  after it, in the same folder: `<doc>.summary.md` (a short précis),
+  `<doc>.flashcards.yaml` (a recall deck) and `<doc>.quiz.yaml` (a
+  multiple-choice check). The summary appears as a second tab beside the
+  document's own words; the deck and the quiz appear at the END of that
+  document's page. None of them appears anywhere else in the site.
 
   An attachment is **part of its document**, not a document. It has no URL of
   its own, no sidebar row, no line in `llms.txt`, and no identity an agent can
@@ -549,6 +550,51 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   kept in the reader's own browser, so it is per-person and per-device, and it
   is not part of the record.
 
+  A **quiz** is the same idea with an answer to choose. Each question carries
+  two to six options, `answer` as the zero-based index of the correct one, a
+  required `explanation`, and an optional `source` naming where in the document
+  the answer lives:
+
+  ```yaml
+  quiz:
+    title: Expense approvals
+    questionsPerRound: 10 # optional; the default
+  questions:
+    - question: Who approves a purchase above the threshold?
+      options:
+        - A second approver, independent of the requester
+        - The requester's own manager, in every case
+        - The finance team, after the purchase completes
+      answer: 0
+      explanation: Why that is right, and why the others are not.
+      source: Approvals — thresholds
+  ```
+
+  The reader sees whether they were right **immediately**, then the
+  explanation — a quiz here teaches through the mistake, and it does not
+  certify anybody, so there is no pass mark. Answers stay in the reader's
+  browser and are sent nowhere. A bank larger than `questionsPerRound` is drawn
+  from at random and offers another round; a smaller one is simply asked in
+  full.
+
+  **`pnpm check` and `pnpm build` both refuse a quiz a reader could pass
+  without reading**, and this is worth knowing before you write one, because
+  it is easy to trip by accident:
+
+  | Refusal                    | Means                                                 |
+  | -------------------------- | ----------------------------------------------------- |
+  | `ksor-quiz-answer-bias`    | more than 60% of answers sit at one option position   |
+  | `ksor-quiz-length-bias`    | picking the longest (or shortest) option usually wins |
+  | `ksor-quiz-answer-run`     | four or more questions in a row share an answer       |
+  | `ksor-quiz-contradiction`  | an explanation calls the marked answer wrong          |
+  | `ksor-quiz-duplicate-stem` | two questions open with the same 60 characters        |
+
+  So: move the correct answer around, and keep the options close in length.
+  The ratio rules do not apply below five questions, where spreading answers
+  would mean the checker choosing them for you. These checks come from the
+  predecessor, where the same mistakes shipped and were found by readers — one
+  quiz had every correct answer in the same position across 451 questions.
+
 - Copy load-bearing values (numbers, thresholds, dates) exactly from their
   source, and name the source in `provenance`.
 

package/templates/scaffold/knowledge/what-is-a-ksor.quiz.yaml

@@ -0,0 +1,90 @@
+# A quiz for what-is-a-ksor.md.
+#
+# Every question and every answer states only what its parent document states —
+# a quiz is a way of checking the record, never a second source. Ask your coding
+# agent to write one from a document, and to check each answer back against it.
+#
+# Two habits worth copying. The options are kept close in LENGTH, because if the
+# correct answer is reliably the longest one a reader passes by looking rather
+# than by reading. And the correct answer moves POSITION between questions: a
+# quiz whose answer is usually B is a quiz you can pass without the document.
+# `pnpm check` and `pnpm build` both refuse a quiz where either is true — the
+# first draft of this one was refused for putting four of five answers at B.
+quiz:
+  title: Check yourself
+  description: Five questions on what this record is, and what it is not.
+questions:
+  - question: A spreadsheet and the ledger disagree about a number. Which one is authoritative?
+    options:
+      - Whichever of the two was most recently edited
+      - The spreadsheet, being closer to the daily work
+      - The ledger, because it is the governing copy
+      - Neither, until a person reconciles the two
+    answer: 2
+    explanation: >
+      A system of record is the copy that governs, so the ledger wins by
+      definition rather than by being newer or closer to the work. Recency is
+      not authority: an edit made this morning in a spreadsheet nobody governs
+      is still ungoverned. Reconciliation is something a record makes possible,
+      not a precondition for having an answer at all.
+    source: The opening definition
+
+  - question: What does a KSoR settle that a traditional system of record does not?
+    options:
+      - The state of a business, such as its balances
+      - Which vendor an organization has chosen to use
+      - How much storage the organization is paying for
+      - What the organization knows and how it operates
+    answer: 3
+    explanation: >
+      A traditional system of record settles the state of a business — what is
+      owed, what is owned, what was transacted. A KSoR settles the layer above
+      it: which policies apply, which thresholds are approved, and what a term
+      means inside this organization. Vendor choice and storage cost are
+      consequences of running one, never what it is authoritative for.
+    source: What this record settles
+
+  - question: Why can an ordinary assistant not tell you which of its sentences were checked?
+    options:
+      - It answers from everything it has ever read
+      - It was not given enough context to work with
+      - Its answers are checked, but only in summary
+      - It lacks permission to reveal its own sources
+    answer: 0
+    explanation: >
+      It answers from everything it has ever read, and nothing in that process
+      separates a checked claim from an unchecked one. This is not a context
+      problem and not a permissions problem: more context cannot create a
+      distinction that was never recorded in the first place. The record closes
+      the gap by governing what gets read.
+    source: Why an assistant cannot answer that question
+
+  - question: What problem does a KSoR exist to solve?
+    options:
+      - Storage costs across a growing organization
+      - Scatter, with no authoritative copy to trust
+      - The speed at which an assistant can reply
+      - The difficulty of writing documentation well
+    answer: 1
+    explanation: >
+      The problem is scatter: knowledge spread across wikis, decks, PDFs,
+      prompts and somebody's memory, with no authoritative answer to which of
+      them an agent should trust. Speed and cost are not what the record
+      addresses, and writing well is valuable but does not by itself tell an
+      agent which of two documents governs.
+    source: The problem it solves
+
+  - question: Abstention — answering "not in this corpus" — is best described as what?
+    options:
+      - An error state the record should minimise
+      - A temporary gap, pending the next ingest
+      - A setting an operator turns on when ready
+      - A correct answer the record is meant to give
+    answer: 3
+    explanation: >
+      Abstention is a correct answer, never an error and never a licence to
+      fall back on general model knowledge. A record that answers everything
+      has stopped being a record of anything in particular. It is not a gap
+      waiting to be filled, and while the gate that enforces it is configured
+      deliberately, the honesty it expresses is the product itself.
+    source: What this record settles, and what it does not

package/templates/scaffold/system/site/app/docs/[[...slug]]/page.tsx

@@ -17,8 +17,9 @@ import { showGovernance } from "@/lib/shared";
 import { RecordToc, TocItems } from "@/components/record-toc";
 import { RecordViews } from "@/components/record-views";
 import { Flashcards } from "@/components/flashcards";
+import { Quiz } from "@/components/quiz";
 import { StudyAids } from "@/components/study-aids";
-import { deckFor, summaryFor } from "@/lib/attachments";
+import { deckFor, quizFor, summaryFor } from "@/lib/attachments";
 import { readingMinutes } from "@/lib/reading-time";
 
 export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
@@ -32,6 +33,7 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
   const summary = summaryFor(page.path);
   const Summary = summary?.body ?? null;
   const deck = deckFor(page.path);
+  const quiz = quizFor(page.path);
   // Counted at BUILD time from the document's own markdown, so the figure is in
   // the shipped HTML for a reader with a failed bundle, a crawler and an agent
   // alike. The predecessor measured the rendered DOM after paint, which put it
@@ -157,7 +159,12 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
           region, so the quiz that will sit beside the deck is a child here and
           not a new argument about where it goes. Renders nothing at all when
           the document has no study aids. */}
-        <StudyAids>{deck === null ? null : <Flashcards deck={deck} />}</StudyAids>
+        {/* Recall first, then the check on it — and each renders only if the
+            document carries one, so a page with just a quiz shows just a quiz. */}
+        <StudyAids>
+          {deck === null ? null : <Flashcards deck={deck} />}
+          {quiz === null ? null : <Quiz quiz={quiz} />}
+        </StudyAids>
         {/* A folder's index page lists what the folder holds. Without it the
           page ended at its own sentence and the documents below it were
           reachable only from the sidebar (research/site-design.md F5). Empty

package/templates/scaffold/system/site/app/global.css

@@ -274,6 +274,74 @@ html > body[data-scroll-locked] {
   --ksor-caution: #e0906e;
 }
 
+/* Right and wrong, for the quiz — the ONE place this record spends green and
+   red, and it earns them: a reader checking an answer is asking a true/false
+   question, and the accent cannot say "this is correct" while also saying
+   "this is what you picked". Both are needed at once when you answer wrongly.
+
+   Colour is never the only channel: the correct option also carries a check,
+   the wrong one a cross, and the line above states the verdict in words — so
+   the pair works for a reader who cannot distinguish them. Declared as
+   light/dark pairs on the root for the reason `--ksor-caution` above records.
+
+   Deliberately NOT `--ksor-caution`, which means "the record withdrew this".
+   A wrong answer is not a governance state. */
+:root {
+  --ksor-correct: #1a7f4b;
+  --ksor-incorrect: #b3261e;
+}
+
+.dark {
+  --ksor-correct: #6edaa0;
+  --ksor-incorrect: #f2897f;
+}
+
+/* The three states an answered question shows at once. Written as CLASSES,
+   the way `.ksor-caution` below is, rather than as Tailwind arbitrary values:
+   `border-[color:var(--x)]` emits a rule whose `var()` did not resolve on the
+   element in a real build (found live 2026-08-23 — the class was present, the
+   rule was in the stylesheet, the token computed correctly on the element, and
+   the border still painted the default hairline). A plain class has none of
+   that ambiguity, and this file is already where this record's semantic colour
+   lives. */
+.ksor-answer-correct {
+  border-color: var(--ksor-correct);
+  background-color: color-mix(in oklab, var(--ksor-correct) 10%, transparent);
+}
+
+.ksor-answer-wrong {
+  border-color: var(--ksor-incorrect);
+  background-color: color-mix(in oklab, var(--ksor-incorrect) 10%, transparent);
+}
+
+/* "This is the one you picked" — kept in the accent, and kept SEPARATE from
+   right/wrong, because after a wrong answer a reader needs all three facts. */
+.ksor-answer-mine {
+  outline: 2px solid var(--color-fd-primary);
+  outline-offset: 1px;
+}
+
+.ksor-answer-correct-text {
+  color: var(--ksor-correct);
+}
+
+.ksor-answer-wrong-text {
+  color: var(--ksor-incorrect);
+}
+
+.dark .ksor-answer-correct,
+.dark .ksor-answer-wrong {
+  background-color: color-mix(in oklab, currentColor 0%, transparent);
+}
+
+.dark .ksor-answer-correct {
+  background-color: color-mix(in oklab, var(--ksor-correct) 14%, transparent);
+}
+
+.dark .ksor-answer-wrong {
+  background-color: color-mix(in oklab, var(--ksor-incorrect) 14%, transparent);
+}
+
 .ksor-caution {
   border-color: color-mix(in oklab, var(--ksor-caution) 32%, transparent);
   border-left-color: var(--ksor-caution);