@panaversity/ksor 0.0.40 → 0.0.42

package/docs/tool-surface.md

@@ -16,26 +16,57 @@ An agent pays for this surface out of its context window, and it pays twice.
 Every tool's name, description and input schema is resident for the whole
 session; every answer spends more.
 
-Measured against a live 81-document record (6,963 chunks), ~4 chars/token:
+**Definitions**, re-measured 2026-08-25 from the served `tools/list` of the
+default registration (~4 chars/token). These depend only on the code, so the
+numbers are exact for every record:
 
 |                                | chars  | ~tokens |                     |
 | ------------------------------ | ------ | ------- | ------------------- |
-| all three tool definitions     | 11,960 | 2,990   | **always resident** |
-| `search` alone                 | 5,383  | 1,346   | always resident     |
-| `outline` + `read`             | 6,571  | 1,643   | always resident     |
-| one `search`, `k=10` (default) | 14,164 | 3,541   | per call            |
-| one `search`, `k=5`            | 8,009  | 2,002   | per call            |
-
-An agent with five records attached carries ~15,000 tokens of definitions before
+| all three, as transmitted      | 16,734 | 4,184   | **always resident** |
+| `search` alone                 | 7,932  | 1,983   | always resident     |
+| `outline` alone                | 3,332  | 833     | always resident     |
+| `read` alone                   | 5,466  | 1,367   | always resident     |
+| `outline` + `read`, if deleted | 8,798  | 2,200   | the saving below    |
+
+**Two measurements, so read the first row apart from the rest.** Each tool's
+row is the JSON of that tool's own object; the first row is the JSON of the
+whole `tools` array, which carries four characters no tool's row does — its
+two brackets and the two separators between three tools. So the three tools
+sum to **16,730** and the array is **16,734**. Deleting a tool saves that
+tool's own row, not a share of the total.
+
+They grew: `search` was 5,383 chars before the trust floor and the governance
+each hit now carries, and `read` 3,396 before it carried the same governance
+block beside the frontmatter. That is the price of an agent being able to tell
+a reviewed document from an unreviewed one, and it is charged once per session.
+The last 520 of them are the price of that signal being HONEST: `trust_tier` is
+derived from reviews a document declares about itself, which no authority list
+gates, and both floors now say so rather than letting `human-reviewed` read as a
+check the record performed.
+
+**Replies** depend on your record's passages, so these are the 2026-08-23
+measurement against a live 81-document record (6,963 chunks), plus the
+governance block every hit — and every `read` reply — now carries: measured
+exactly at **262 chars** for a document with a verification and an approval,
+**133** where a level-0 record has neither. They were NOT re-measured against
+that record:
+
+|                                | ~chars | ~tokens |          |
+| ------------------------------ | ------ | ------- | -------- |
+| one `search`, `k=10` (default) | 16,784 | 4,196   | per call |
+| one `search`, `k=5`            | 9,319  | 2,330   | per call |
+| one `search`, `k=3`            | 4,939  | 1,235   | per call |
+
+An agent with five records attached carries ~20,000 tokens of definitions before
 doing any work.
 
 ## The three edits that pay
 
 ### 1. Delete a tool nothing calls
 
-The biggest win, and the easiest — delete its `registerTool` block. Measured
-live: a registration keeping only a renamed `search` served **5,337** bytes
-against the default's 11,960.
+The biggest win, and the easiest — delete its `registerTool` block. Dropping
+`outline` and `read` takes **8,798 chars (~2,200 tokens)** off every session,
+whether or not the agent would ever have called them.
 
 ### 2. Say what the record covers
 
@@ -51,18 +82,37 @@ Your prose goes **above** `FLOOR.search`, never instead of it — see below.
 
 ### 3. Set `k`
 
-`k` is the lever on reply size: 10 costs ~3,500 tokens a call, 5 costs ~2,000.
+`k` is the lever on reply size: 10 costs ~4,200 tokens a call, 5 costs ~2,300.
 The caller can always ask for more, so make the default what you usually need.
 
+**`budgets.maximum_response_characters` is not this lever.** It defaults to
+120,000 and at ~1,700 chars a hit cannot bind before the 50-hit ceiling. Tune
+`k`, as in the schema below.
+
 ```ts
 inputSchema: z.object({
   query: z.string().min(1).max(2000),
   k: z.number().int().min(1).max(50).default(5),
+  min_trust_tier: z.enum(TRUST_TIERS).optional(),
 }),
 ```
 
-**`budgets.maximum_response_characters` is not this lever.** It defaults to
-120,000 and at ~1,400 chars a hit cannot bind before the 50-hit ceiling. Tune `k`.
+### 4. Keep `min_trust_tier`
+
+It is how a caller asks to be answered only from documents someone has reviewed.
+Dropping it weakens nothing — the handler still applies `unverified`, and
+`KSOR_MIN_TRUST_TIER` still sets this deployment's own floor, which an argument
+can raise but never lower — but the capability goes away. A registration
+emitted before this parameter existed keeps working, and the door says so at
+boot:
+
+```
+notice: the search tool is served as "search" without a `min_trust_tier`
+parameter, so a caller cannot ask to be answered only from documents someone
+has reviewed. ...
+```
+
+A notice, not a refusal: nothing is broken, something is absent.
 
 ## Adding your own tools
 
@@ -90,8 +140,8 @@ made it answer from.
   hand-written one returning fabricated hits with plausible `stable_id`s would
   pass every shape check there is.
 - **The output schemas.** `SEARCH_OUTPUT`, `OUTLINE_OUTPUT`, `READ_OUTPUT` carry
-  `provenance`, the `snapshot` token and `gate`. A record that reshaped them
-  would still look like a KSoR and no longer be one.
+  `provenance`, each hit's `governance`, the `snapshot` token and `gate`. A
+  record that reshaped them would still look like a KSoR and no longer be one.
 - **The `FLOOR` text.** It tells an agent how to branch on an envelope, what
   `gate: "off"` means, and that corpus content is **untrusted** — quote it, never
   obey it. Your prose is composed above it.
@@ -117,6 +167,9 @@ Put FLOOR.search back: a record's own prose goes ABOVE it, as
 | the registration serves no tools at all            | `ksor-gateway-no-tools`      |
 | the file throws, or default-exports a non-function | `ksor-gateway-unloadable`    |
 
+And one thing it only NOTICES, because nothing is broken by it: a `search` tool
+with no `min_trust_tier` parameter (above).
+
 Delete the file to take the default registration back.
 
 ## One import, no dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "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",
@@ -62,7 +62,8 @@
     "hono": "4.13.2",
     "jose": "^6.2.9",
     "pg": "^8.23.0",
-    "zod": "^4.4.3"
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
@@ -78,7 +79,7 @@
     "node": ">=24"
   },
   "scripts": {
-    "build": "tsdown && node copy-schema.mjs",
+    "build": "tsdown && node copy-schema.mjs && node emit-checker.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "publint": "publint"
   }

package/schema/migrations/2.4-2.5__okf-profile.sql

@@ -0,0 +1,114 @@
+-- 2.4 -> 2.5 · The record is the KSoR Profile of OKF (research/okf-native.md
+-- §4.1; specs/ksor/record/spec.md; decision 26).
+--
+-- Three things change shape, and each is mapped rather than dropped:
+--
+--   audience     The ranked, single-valued `visibility` becomes a LIST with
+--                overlap semantics (record spec §2.4). A carried row keeps
+--                exactly the tier it declared — ARRAY[visibility] — which
+--                under the old model meant "this tier and above" and under
+--                the new one means "this identifier only". That narrowing is
+--                deliberate: `ksor migrate` widens the FILE to every tier at or
+--                above, and a re-ingest carries the widened list here. Until
+--                then a pre-2.5 generation refuses to serve (GOVERNANCE_SINCE),
+--                so no viewer is answered from a half-mapped row.
+--   doc_status   approved -> stable, review -> draft, superseded -> deprecated;
+--                anything else the author wrote is not a profile status and
+--                becomes NULL (the checker refuses it on the next ingest). The
+--                CHECK then closes the set, because the lifecycle predicate
+--                keys on it.
+--   trust_tier   0 unverified · 1 machine-confirmed · 2 human-reviewed. A
+--                carried row has no `verified` list, so it is 0: the honest
+--                state of a stable, approved, unverified concept (plan §2.13).
+--
+-- The run row gains the build it published (`build_id`), the policy it was
+-- checked against (registry + authorities, and its digest) and the ledger's id
+-- set; the denylist row gains the ledger entry that wrote it and, nullable,
+-- the one that revoked it — the `DENIED` seam denies only `revoked_at IS NULL`.
+--
+-- compatible_from: 2.5
+
+ALTER TABLE content_nodes
+    ADD COLUMN IF NOT EXISTS audience       TEXT[],
+    ADD COLUMN IF NOT EXISTS sources        JSONB,
+    ADD COLUMN IF NOT EXISTS verified       JSONB,
+    ADD COLUMN IF NOT EXISTS generated      JSONB,
+    ADD COLUMN IF NOT EXISTS approval       JSONB,
+    ADD COLUMN IF NOT EXISTS deprecated     JSONB,
+    ADD COLUMN IF NOT EXISTS effective_from TIMESTAMPTZ,
+    ADD COLUMN IF NOT EXISTS stale_after    TIMESTAMPTZ,
+    ADD COLUMN IF NOT EXISTS trust_tier     SMALLINT;
+
+UPDATE content_nodes
+   SET audience = ARRAY[visibility]
+ WHERE visibility IS NOT NULL AND visibility <> '' AND audience IS NULL;
+
+UPDATE content_nodes
+   SET doc_status = CASE doc_status
+                      WHEN 'approved'   THEN 'stable'
+                      WHEN 'review'     THEN 'draft'
+                      WHEN 'superseded' THEN 'deprecated'
+                      WHEN 'draft'      THEN 'draft'
+                      WHEN 'stable'     THEN 'stable'
+                      WHEN 'deprecated' THEN 'deprecated'
+                      ELSE NULL
+                    END
+ WHERE doc_status IS NOT NULL;
+
+UPDATE content_nodes SET trust_tier = 0 WHERE kind = 'document' AND trust_tier IS NULL;
+
+ALTER TABLE content_nodes DROP COLUMN IF EXISTS visibility;
+ALTER TABLE content_nodes
+    ADD CONSTRAINT nodes_doc_status_profile
+        CHECK (doc_status IS NULL OR doc_status IN ('draft','stable','deprecated')),
+    ADD CONSTRAINT nodes_trust_tier_range
+        CHECK (trust_tier IS NULL OR trust_tier BETWEEN 0 AND 2);
+CREATE INDEX IF NOT EXISTS idx_nodes_audience ON content_nodes USING gin (audience);
+
+COMMENT ON COLUMN content_nodes.audience IS
+  'ksor.audience, a list; a section carries the union of its descendants'' lists so `audience && viewer` admits it iff a descendant is visible. NULL on a pre-2.5 row that declared no visibility.';
+COMMENT ON COLUMN content_nodes.trust_tier IS
+  '0 unverified, 1 machine-confirmed, 2 human-reviewed — derived from `verified` at ingest, never authored.';
+
+ALTER TABLE ingestion_runs
+    ADD COLUMN IF NOT EXISTS build_id      TEXT,
+    ADD COLUMN IF NOT EXISTS policy        JSONB,
+    ADD COLUMN IF NOT EXISTS policy_sha256 TEXT,
+    ADD COLUMN IF NOT EXISTS ledger_ids    TEXT[];
+
+COMMENT ON COLUMN ingestion_runs.build_id IS
+  'build.lock.json''s build_id — the publication this generation was ingested from; NULL on a pre-2.5 run.';
+COMMENT ON COLUMN ingestion_runs.policy IS
+  'The Governance Policy the generation was checked against: {audiences, approval_authorities, takedown_authorities, ownership}. The door binds to this row, never to the file.';
+COMMENT ON COLUMN ingestion_runs.ledger_ids IS
+  'Every id in .ksor/takedowns.yaml at ingest, in file order — the baseline ksor-ledger-shrank compares the next ingest against.';
+
+ALTER TABLE takedown_denylist
+    ADD COLUMN IF NOT EXISTS ledger_id         TEXT,
+    ADD COLUMN IF NOT EXISTS actor             TEXT,
+    ADD COLUMN IF NOT EXISTS applied_at        TIMESTAMPTZ,
+    ADD COLUMN IF NOT EXISTS revoked_ledger_id TEXT,
+    ADD COLUMN IF NOT EXISTS revoked_at        TIMESTAMPTZ,
+    -- A carried row predates the ledger entirely, so `present` is the only
+    -- honest default: nothing in the repository yet says the file was deleted.
+    -- The first ingest folds the ledger and writes what it actually says.
+    ADD COLUMN IF NOT EXISTS expected          TEXT NOT NULL DEFAULT 'present';
+ALTER TABLE takedown_denylist
+    ADD CONSTRAINT takedown_expected_values CHECK (expected IN ('present','removed'));
+
+COMMENT ON COLUMN takedown_denylist.ledger_id IS
+  'The .ksor/takedowns.yaml entry that wrote this row. NULL = written before the ledger existed; the boot gate refuses it (ksor-takedown-unledgered) until an ingest attaches one by stable_id.';
+COMMENT ON COLUMN takedown_denylist.expected IS
+  'What the ledger expects of the FILE, as the latest amendment left it: present, or removed for a document withdrawn and then deliberately deleted. The orphan check skips `removed`; the DENIED seam never reads it, so a removed document stays denied.';
+COMMENT ON COLUMN takedown_denylist.revoked_at IS
+  'Set by a revocation entry; the DENIED seam denies only rows where this is NULL. A re-denial clears it — the ledger holds the history, the row holds the state.';
+
+-- The author's own frontmatter bytes, so `read` can return them intact rather
+-- than re-serialising the parsed columns into a document the record does not
+-- contain. Additive and nullable: a carried row simply has none, and such a
+-- generation is refused at boot anyway (GOVERNANCE_SINCE).
+ALTER TABLE sources
+    ADD COLUMN IF NOT EXISTS frontmatter TEXT;
+
+COMMENT ON COLUMN sources.frontmatter IS
+  'The file''s frontmatter block, byte-exact as authored (comments and unknown keys included). Served verbatim by `read`; never re-serialised.';

package/schema/schema.sql

@@ -49,6 +49,15 @@ CREATE TABLE ingestion_runs (
     -- record with an audience model must refuse to serve such a generation
     -- rather than quietly publish restricted documents (2.4).
     schema_version         TEXT,
+    -- 2.5: the publication this generation was ingested from (build.lock.json's
+    -- build_id), the Governance Policy it was checked against — registry and
+    -- authorities as a row, with its digest, so the door binds to the row and
+    -- the served container never needs the file — and the ledger's id set, the
+    -- baseline the next ingest's ksor-ledger-shrank compares against.
+    build_id               TEXT,
+    policy                 JSONB,
+    policy_sha256          TEXT,
+    ledger_ids             TEXT[],
     UNIQUE (tenant_id, corpus_id, generation)
 );
 
@@ -71,11 +80,33 @@ CREATE TABLE content_nodes (
     -- surface reads one source instead of re-deriving it from markdown. `status`
     -- above is the SERVING state of the row; `doc_status` is what the document says.
     corpus_id     TEXT,                               -- which record this node belongs to
-    visibility    TEXT,                               -- audience tier; NULL = instance default_visibility
-    doc_status    TEXT,                               -- draft / approved / superseded, as authored
+    -- The KSoR Profile of OKF (2.5, record spec §2): `ksor.audience` as a LIST
+    -- with overlap semantics — a section carries the union of its descendants'
+    -- lists, so `audience && viewer` admits it iff a descendant is visible;
+    -- the authored lifecycle status, closed to the profile's set; the trust
+    -- vocabulary as JSONB; effectivity and staleness as instants; and the trust
+    -- tier derived from `verified` at ingest (0 unverified, 1 machine-confirmed,
+    -- 2 human-reviewed). `provenance` (2.2) stays for a carried row; a 2.5
+    -- ingest writes `sources`.
+    audience      TEXT[],
+    -- Named, not auto-named: the 2.4 -> 2.5 migration adds this same CHECK by
+    -- name, and an unnamed inline constraint is auto-named after the column, so a
+    -- migrated database and a fresh one carried the SAME rule under two different
+    -- names — one schema nobody could diff (schema-parity.db.test.ts).
+    doc_status    TEXT CONSTRAINT nodes_doc_status_profile
+                    CHECK (doc_status IS NULL OR doc_status IN ('draft','stable','deprecated')),
     owner         TEXT,
-    provenance    JSONB,                              -- where the claims come from, as authored
-    superseded_by TEXT,                               -- stable_id of the replacement
+    provenance    JSONB,                              -- pre-profile `provenance:`, carried rows only
+    superseded_by TEXT,                               -- ksor.superseded_by, as a stable_id
+    sources       JSONB,
+    verified      JSONB,
+    generated     JSONB,
+    approval      JSONB,
+    deprecated    JSONB,
+    effective_from TIMESTAMPTZ,
+    stale_after   TIMESTAMPTZ,
+    trust_tier    SMALLINT CONSTRAINT nodes_trust_tier_range
+                    CHECK (trust_tier IS NULL OR trust_tier BETWEEN 0 AND 2),
     created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
     updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
     CONSTRAINT nodes_stable_uniq  UNIQUE (tenant_id, generation, stable_id),
@@ -88,12 +119,10 @@ CREATE TABLE content_nodes (
 CREATE INDEX idx_nodes_gen      ON content_nodes (tenant_id, generation, kind);
 CREATE INDEX idx_nodes_parent   ON content_nodes (parent_id);
 CREATE INDEX idx_nodes_keywords ON content_nodes USING gin (keywords);
--- NO index on visibility. The serving predicate is
--- `coalesce(n.visibility, <runtime GUC>) = ANY(...)`, and a plain btree cannot
--- serve a coalesce over a value that is only known per transaction — the index
--- would be built and maintained and never read, which is exactly the defect
--- the HNSW arm was just fixed for. The audience filter rides the
--- (tenant_id, generation, kind) index that every serving arm already uses.
+-- The overlap predicate (`audience && viewer`) is an array-overlap, which a GIN
+-- serves and a btree cannot; the ranked predicate it replaces rode the
+-- (tenant_id, generation, kind) index through a coalesce no index could read.
+CREATE INDEX idx_nodes_audience ON content_nodes USING gin (audience);
 CREATE UNIQUE INDEX nodes_root_slug_uniq ON content_nodes (tenant_id, generation, slug) WHERE parent_id IS NULL;
 
 CREATE TABLE slug_aliases (
@@ -117,6 +146,12 @@ CREATE TABLE sources (
     embedding_model TEXT NOT NULL,
     chunk_policy    TEXT NOT NULL,
     source_commit   TEXT,
+    -- 2.5: the file's frontmatter block, byte-exact as the author wrote it —
+    -- comments and unknown keys included (OKF §11). `read` serves it back
+    -- verbatim; a re-serialisation from the parsed columns would be a
+    -- DIFFERENT document wearing the record's name. NULL for a source with no
+    -- frontmatter, and for a pre-2.5 carried row.
+    frontmatter     TEXT,
     seeded_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
     updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
     PRIMARY KEY (tenant_id, generation, source_id),
@@ -187,6 +222,31 @@ CREATE TABLE takedown_denylist (
     scope      TEXT NOT NULL DEFAULT 'node' CHECK (scope IN ('node','subtree')),
     reason     TEXT NOT NULL,
     created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    -- 2.5: the row is the STATE, the ledger (.ksor/takedowns.yaml) is the
+    -- history. `ledger_id` names the entry that wrote the row (NULL = written
+    -- before the ledger existed — the boot gate refuses it until an ingest
+    -- attaches one by stable_id); a revocation sets `revoked_ledger_id` /
+    -- `revoked_at`, and the DENIED seam denies only `revoked_at IS NULL`; a
+    -- re-denial clears them. Rows are never deleted.
+    ledger_id         TEXT,
+    actor             TEXT,
+    applied_at        TIMESTAMPTZ,
+    revoked_ledger_id TEXT,
+    revoked_at        TIMESTAMPTZ,
+    -- What the ledger expects of the FILE, as the latest amendment left it
+    -- (record spec §5). `present` is the ordinary case. `removed` says the
+    -- document was withdrawn and then deliberately deleted — a state the boot
+    -- gate must not read as an orphaned denial, because the honest answer to
+    -- "is there still a node with this id?" is no, forever. Without this column
+    -- every such denial refused `ksor ingest` and `ksor serve` permanently, and
+    -- the remedy the refusal printed (`--removed`) moves no row, so the only
+    -- escape was to un-withdraw the document (review 2026-08-25).
+    --
+    -- It does NOT weaken the denial: `removed` rows stay in force and the
+    -- DENIED seam never reads this column. It records what happened to the
+    -- FILE, not whether the withdrawal still stands.
+    expected   TEXT NOT NULL DEFAULT 'present'
+                 CONSTRAINT takedown_expected_values CHECK (expected IN ('present','removed')),
     PRIMARY KEY (tenant_id, corpus_id, stable_id)
 );
 
@@ -227,10 +287,13 @@ CREATE TABLE schema_meta (
 -- 2.4 stamps each generation with the schema it was built against, so a
 -- generation predating the governance columns can be REFUSED rather than served
 -- at default_visibility.
--- Both are additive and nullable, so a 2.0 reader still reads a 2.2 database —
--- compatible_from stays 2.0. Existing databases move forward through
--- schema/migrations/; schema.sql provisions a FRESH one at the current version.
-INSERT INTO schema_meta (schema_version, compatible_from) VALUES ('2.4', '2.0');
+-- 2.5 puts the KSoR Profile on the node row (audience list, closed status set,
+-- trust vocabulary, effectivity, trust tier), the policy and the lock on the
+-- run, and the ledger on the denylist row; it DROPS `visibility`, so a 2.4
+-- reader's predicate no longer resolves — compatible_from moves to 2.5.
+-- Existing databases move forward through schema/migrations/; schema.sql
+-- provisions a FRESH one at the current version.
+INSERT INTO schema_meta (schema_version, compatible_from) VALUES ('2.5', '2.5');
 
 CREATE OR REPLACE FUNCTION touch_updated_at() RETURNS trigger AS $$
 BEGIN NEW.updated_at = now(); RETURN NEW; END; $$ LANGUAGE plpgsql;

package/templates/scaffold/.agents/skills/add-sources/SKILL.md

@@ -2,7 +2,7 @@
 name: add-sources
 description: Turn source material — documents, pages, pasted text, notes — into governed knowledge in knowledge/. Use when the owner shares material to add, says "add this to the knowledge base", or asks how to get existing content in. Not for editing the site.
 metadata:
-  version: "1.2.0"
+  version: "1.3.0"
 ---
 
 # Add sources
@@ -16,31 +16,76 @@ The rules that make it _governed_ rather than merely stored:
   hyphens, a folder per natural grouping. Plain CommonMark `.md` — if the
   source is rich (tables, images), tables become markdown tables and images
   land _beside the document_ with relative links.
-- A folder's front page is `<folder>/index.md`; reading order is the
-  `order:` frontmatter key (ordered documents first, ascending; the rest
-  follow alphabetically) — never `meta.json` or `sidebar_position`.
-- Frontmatter: `title` and `status: draft` always; add `owner` (who stands
-  behind this content) and `provenance` (a list naming the actual sources —
-  file names, systems, people, dates) whenever the owner can tell you.
-  Precision matters: "Finance policy manual §4.2, 2025 edition" governs;
-  "internal docs" does not.
-- When `instance.md` declares `audiences:`, ask the owner which audience the
-  new material belongs to and write it as `visibility:` — never guess that
-  restricted material is public.
+- A folder's `index.md` is GENERATED by `ksor build` and committed — never
+  author one. A folder's own introduction is a named document inside it,
+  such as `overview.md`. Reading order is the `order:` frontmatter key
+  (ordered documents first, ascending; the rest follow alphabetically) —
+  never `meta.json` or `sidebar_position`.
+- Frontmatter is the KSoR Profile of OKF. Always: `type: Document`, `title`,
+  `description` (one sentence), `status: draft`, and `ksor.audience` (a
+  list). Reach for a reserved `type` — `Policy`, `Procedure`, `Control`,
+  `Standard`, `Definition`, `Decision Record`, `Example`,
+  `Attested Computation` — when the knowledge really is one; those additionally require `sources` and
+  `ksor.owner`, which is the point of them.
+
+  ```yaml
+  ---
+  type: Policy
+  title: Purchase approval
+  description: Who may approve a purchase, at which thresholds.
+  status: draft
+  sources:
+    - id: fin-2025
+      title: Finance policy manual §4.2, 2025 edition
+      resource: https://intranet.example.com/finance/manual.pdf
+  ksor:
+    audience: [public]
+    owner: team:finance
+  ---
+
+  A purchase above 10,000 needs a director's signature. [^fin-2025]
+
+  [^fin-2025]: Finance policy manual §4.2, 2025 edition.
+  ```
+
+  Every source needs a `resource` — a URL where one exists, otherwise the
+  scope descriptor that names it ("Finance policy manual §4.2, 2025
+  edition"). Precision matters: that governs; "internal docs" does not. A
+  claim cites ONE of them by footnote, and the label must match a
+  `sources[].id` or the checker refuses it.
+
+- `status: draft` always, and never anything else from here: `stable` needs
+  `ksor.approval` by an actor `.ksor/governance.yaml` names, and recording
+  an approval nobody gave is the one thing this skill must never do. Ask the
+  owner; if they approve, THEY are the approver and you write down what they
+  said.
+- When `.ksor/governance.yaml` registers audiences, ask the owner which of
+  them may read the new material and list every one in `ksor.audience` —
+  never guess that restricted material is public, and never write an
+  identifier the registry does not declare (the checker refuses it, because
+  a typo reads as a restriction).
 
 ## Fidelity rules
 
 - **Copy load-bearing values exactly** — numbers, thresholds, dates, names.
   Never round, never paraphrase a figure.
-- **Two disagreeing sources stay two statements**, each with its provenance
-  — never smooth a conflict into one invented truth; flag it to the owner.
+- **Two disagreeing sources stay two statements**, each with its own
+  footnote — never smooth a conflict into one invented truth; flag it to the
+  owner.
 - **Do not fill gaps from general knowledge.** If the source doesn't cover
   something, the record doesn't either — that boundary is the product.
-- A document replacing an older one: mark the old one `status: superseded`
-  with `superseded_by:` pointing at the new — never delete it.
+- A document replacing an older one: mark the old one `status: deprecated`
+  with `ksor.deprecated: { by, at }` (a takedown authority the policy names, or
+  the owner an `ownership:` rule resolves — never the document's own
+  `ksor.owner`; ask, never guess) and `ksor.superseded_by:` naming the
+  successor by id (`policies/refunds-v2`, no `./` and no `.md`) — never
+  delete it. The successor must exist, be `stable`, and be readable by every
+  reader of the deprecated one.
 
 ## Finish every batch
 
 Run `pnpm check` and fix what it reports (its errors explain themselves),
-then show the owner the rendered result (`pnpm dev`) — the site is the
-review surface: you write, they check.
+then `ksor build` to regenerate every folder's `index.md` and write
+`build.lock.json`, and commit both with the documents. Then show the owner
+the rendered result (`pnpm dev`) — the site is the review surface: you write,
+they check.

package/templates/scaffold/.agents/skills/format-checker/SKILL.md

@@ -2,45 +2,54 @@
 name: format-checker
 description: The record's format rules as a runnable check — frontmatter, filenames, links, structure. Use before handing off any change to knowledge/, when a check fails and you need to fix it, or when unsure whether a document is well-formed. Run with `pnpm check` (or node .agents/skills/format-checker/check.mjs).
 metadata:
-  version: "1.2.0"
+  version: "2.1.0"
 ---
 
 # Format checker
 
-`pnpm check` runs `check.mjs` — dependency-free Node, owned by this repo. It
-enforces what AGENTS.md states in prose:
+`pnpm check` runs `check.mjs` — a self-contained Node program that needs no
+install. It is **generated** by ksor from the same rule set `ksor build` and
+`ksor ingest` run, so the three can never disagree about what a well-formed
+record is. Do not edit it: `ksor init` writes it and `ksor migrate` rewrites
+both copies of it when you upgrade the tool, so an edit is overwritten rather
+than kept. It is read-only in the other direction too — it reports, and never
+rewrites a file.
 
-- `knowledge/` holds CommonMark `.md` and images only — no `.mdx`, no
-  `meta.json`, no other file types — and it is never empty; a record with no
-  documents stands behind nothing.
-- Every document carries `title` + `status` (level-0 requirement); the full
-  allowed key set is closed; a `superseded` document names a `superseded_by`
-  that resolves to a document that exists.
-- Filenames are portable identities: lowercase, Windows-safe, no spaces, no
-  case-collisions, no `foo.md` + `foo/index.md` pairs, no parentheses.
-  (`.DS_Store` and friends are skipped, never reported.)
-- Relative links resolve and never leave `knowledge/` — inline,
-  `<angle-bracketed>`, and reference-style (`[text][label]` with its
-  `[label]: target` definition) alike. Links inside code spans and fenced
-  blocks are code, not links, and are ignored.
-- `instance.md` exists, is `format: 1`, and carries only the keys the format
-  defines — an unknown key is named, never ignored.
-- The audience model, when there is one: `audiences:` is ordered least- to
-  most-restricted with `public` first, no duplicates, and never without
-  `default_visibility:`; a document's `visibility:` names one of the declared
-  audiences; and no link or `superseded_by:` points from a wider audience at a
-  narrower one — the leak no single build can catch, since the build that
-  publishes the pointer has already dropped its target. A record that declares
-  no `audiences:` is checked exactly as it was before the key existed.
+If its refusals contradict this document, the checker is older than the record:
+upgrade `@panaversity/ksor` and re-run `ksor migrate`, and never "fix" the
+record by undoing what the migration wrote.
+
+What it holds the record to (the full contract is ksor's record spec):
+
+- Every document in `knowledge/` is a concept in the KSoR Profile of OKF:
+  frontmatter is real YAML carrying `type`, `title`, `description`, `status`
+  (`draft | stable | deprecated`) and `ksor.audience` (a list; `public` or
+  audiences registered in `.ksor/governance.yaml`). A `stable` concept carries
+  `generated` and an approval by an authorised actor; a `deprecated` one says
+  who deprecated it and usually names its successor; a reserved type (`Policy`,
+  `Procedure`, …) names `sources` and `ksor.owner`. Every timestamp is an
+  instant with an offset; every footnote label matches a `sources[].id`.
+- `.ksor/governance.yaml` exists and names approval and takedown authorities;
+  `.ksor/takedowns.yaml` is append-only, every entry by a takedown authority,
+  and never names a concept that no longer exists.
+- `index.md` files are generated by `ksor build`, never authored — a stale or
+  missing one is refused (`ksor-index-stale`; run `ksor build`). `log.md` and
+  `README.md` are reserved names.
+- Filenames are portable identities: lowercase ascii, no spaces, no
+  case-collisions, no `x.md` beside `x/`, no parentheses or leading
+  underscore. `knowledge/` holds `.md`, companions (`<doc>.summary.md`,
+  `<doc>.{flashcards,quiz,slides}.yaml`) and images only.
+- Links resolve inside `knowledge/` — inline, `<angle-bracketed>` and
+  reference-style alike; code is never a link — and never reach a document
+  that not every reader of the source may read (the widening rule).
+- `instance.md` is `format: 2` with the closed key set the profile defines.
 - `CLAUDE.md` stays a one-line pointer; `.agents/skills/` and
-  `.claude/skills/` hold the same files byte for byte **in both directions**
-  (a file only one tree carries is a rule nobody reviewed); the site contains
-  no content files.
+  `.claude/skills/` hold the same files byte for byte in both directions; the
+  site contains no content files.
 
-Every failure prints what is wrong, why the rule exists, and the fix — obey
-the printed fix literally; if it doesn't resolve the problem, that is a bug
-worth reporting to ksor.
+Every failure prints where, the rule's slug (`problem: ksor-…`), why the rule
+exists, and the fix — obey the printed fix literally; if it doesn't resolve
+the problem, that is a bug worth reporting to ksor.
 
 When you edit any skill under `.agents/skills/`, re-copy it to
-`.claude/skills/` — the checker holds the two trees identical, and it now
-notices a file added on either side.
+`.claude/skills/` — the checker holds the two trees identical.