@panaversity/ksor 0.0.54 → 0.0.56

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

@@ -1,91 +1,136 @@
 ---
 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.
+description: Turn what the owner has into governed knowledge in knowledge/ — a document, a page, pasted text, notes, or something nobody ever wrote down that they tell you. Use when the owner shares material to add, says "add this to the knowledge base", asks how to get existing content in, or wants to write down what they know from memory with no source to hand. Not for editing the site.
 metadata:
-  version: "1.3.0"
+  version: "2.0.0"
 ---
 
 # Add sources
 
-Converting material into the record is the everyday work of this project.
-The rules that make it _governed_ rather than merely stored:
-
-## Placement and shape
-
-- One document per topic, under `knowledge/`, path = identity: lowercase,
-  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 `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 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: 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 `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.
+Getting knowledge into the record is the everyday work of this project. The
+rules that make it _governed_ are in `AGENTS.md` → "Writing knowledge" (shape,
+frontmatter, audience, `draft` until the owner approves, copy values exactly,
+never invent). This file is the ACT: how a source becomes a document that
+passes those rules, whatever kind of source it is.
+
+## The source is one of two kinds — and usually both
+
+**A file** — PDF, Word, slides, HTML, a Notion export, pasted text — is
+knowledge that already exists somewhere. Your job is to move it without losing
+anything: convert it, structure it, and prove every load-bearing value survived.
+
+**A person** — "it's just how we do it" — is knowledge that exists nowhere
+yet. Your job is to draw it out by asking, write it as the record and not as a
+transcript, and record only what they confirm.
+
+A real owner has both: the policy PDF, and the exception everyone knows that
+the PDF never mentions. So the person step runs EVERY time, after the file:
+"what does this not cover?" is the question that finds the pages nobody wrote.
+
+## When the source is a file
+
+1. **Extract the text first, into a scratch file outside `knowledge/`.** The
+   extraction is what you convert from and what you verify against, so it has
+   to be a file you can grep, not something you remember reading:
+
+   | format                   | extractor                                                           |
+   | ------------------------ | ------------------------------------------------------------------- |
+   | PDF                      | `pdftotext -layout in.pdf /tmp/in.txt` (poppler)                    |
+   | docx / odt / html / epub | `pandoc in.docx -t gfm -o /tmp/in.md`                               |
+   | docx on macOS            | `textutil -convert txt in.docx -output /tmp/in.txt` (built in)      |
+   | anything                 | `markitdown in.pdf > /tmp/in.md`, if installed                      |
+   | Notion / Obsidian export | already markdown — no extraction needed; the file IS the extraction |
+
+   None on `PATH`? Read the file directly (your Read tool opens PDFs) and say so
+   in your report — there is then no extraction to verify against, and step 5
+   degrades to re-reading the source by eye. That is a weaker check, and the
+   owner must be told it was the check that ran.
+
+   **Empty extraction — whitespace, form-feeds, nothing — means the PDF has no
+   text layer.** Stop and tell the owner: "This is a scanned image. I can read it
+   as a picture, but I cannot promise the numbers in it are right, and a wrong
+   threshold in a system of record is worse than a missing page. Give me a text
+   PDF, or paste the section you need." Do not OCR it and hope.
+
+2. **Decide the shape of the RECORD, not of one file.** A 200-page manual is not
+   one document. One document per topic — the unit someone would ask a question
+   about — placed where its path is the identity it should have, with `order:`
+   set to reading order. Show the owner the proposed tree before writing it.
+
+3. **Convert to CommonMark a person would have written.** Real headings from
+   the document's own structure (never an `# h1` — the title is the frontmatter),
+   real lists, real tables; images extracted and placed beside the document
+   with relative links. Strip page furniture: running headers and footers, page
+   numbers, "Page 4 of 12", the table of contents. Keep the source's own words
+   for anything load-bearing.
+
+4. **Name the source precisely** in `sources` — a URL where one exists,
+   otherwise the descriptor that governs ("Finance policy manual §4.2, 2025
+   edition"; "internal docs" governs nothing) — and cite it from the claim with
+   a footnote whose label is that source's `id`.
+
+5. **Verify — do not trust yourself.** Run the shipped check against the
+   extraction from step 1:
+
+   ```sh
+   node .agents/skills/add-sources/verify.mjs /tmp/in.txt knowledge/<path>.md
+   ```
+
+   It lists every load-bearing token in the document's body — numbers, dates,
+   thresholds, codes, capitalised names — that does not appear in the
+   extraction. Each one is either a value you changed (fix it, verbatim) or a
+   value you introduced (delete it, or turn it into an `Open question:` line
+   for the owner). A value that passes was in the source; nothing more is
+   claimed. Frontmatter is exempt, because its title and description are your
+   words by design.
+
+## When the source is a person
+
+1. **Ask, one question at a time, in their words.** Who triggers this? What
+   happens first, then next? Who has to approve, and at what threshold? What
+   goes wrong, and what is the exception? Follow up until each answer is
+   concrete enough that someone who was not in the room could act on it —
+   "what would someone actually ask this?" gets further than "define the
+   boundary".
+
+2. **Draft as the record, not as a transcript.** One document per topic. Their
+   sentences, tightened — never your inference about what they must have
+   meant. Anything they did not say, or said they were not sure of, becomes an
+   `Open question:` line in the document. It does not become prose.
+
+3. **The source is the conversation, and it is named like any other.** No
+   `provenance:` key exists; the attestation goes in `sources`:
+
+   ```yaml
+   sources:
+     - id: ops-interview-2026-08-21
+       title: Interview with J. Smith, Head of Operations
+       resource: "Interview with human:jsmith (Head of Operations), 2026-08-21T10:00:00Z, conducted by human:you"
+   ```
+
+   Who, their role, the instant, and who asked. That is a claim nobody can
+   check against a file, and the pull request that adds it is the only thing
+   standing behind it — say so if the owner asks what "verified" would mean
+   here. No transcript is kept: raw unreviewed speech does not belong in a
+   governed record, and the checker refuses a `.txt` there anyway.
+
+4. **Two people describe one process differently — surface it, never smooth
+   it.** Two cited statements, each with its own footnote, and the
+   disagreement flagged to the owner. Which one becomes `stable` is an
+   approval, not an edit.
+
+## Finish — every batch, either kind
+
+- `pnpm check`, and obey what it prints.
+- `ksor build`: it regenerates every folder's `index.md` and writes the lock.
+- **Read it back on the site.** `pnpm dev` renders the real page, drafts
+  marked; that page is what the owner confirms against, not a message in a
+  terminal. "Their words, tightened — never your invention" is the standard,
+  and it is theirs to say whether you met it.
+- **Then ask them to approve it — and write down what they said.** A draft
+  reaches no machine surface: no `llms.txt`, no `/md/` twin, nothing for an
+  agent to cite. Until the owner says "approved" and you record
+  `ksor.approval: { by: <their handle>, at: <now> }` with `status: stable`,
+  the record still publishes nothing of theirs. Never record an approval
+  nobody gave.
+- Commit the documents, the indexes and the lock together.

package/templates/scaffold/.claude/skills/add-sources/verify.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Did the document keep its source's load-bearing values?
+//
+//   node verify.mjs <extraction.txt> <document.md>
+//
+// Exit 0 when every load-bearing token in the document's BODY appears in the
+// extraction; exit 1 and print each one that does not, one per line.
+//
+// What "load-bearing" means here: numbers (with their separators — 10,000 and
+// 10000 are different claims about the source), dates, codes, and runs of two
+// or more capitalised words (a name). Matched case-folded and with whitespace
+// collapsed, because an extraction shouts its headings and wraps its lines.
+//
+// What this proves, and no more: a token that PASSES is present in the source.
+// A token that FAILS was changed or introduced — either way, look at it. It
+// cannot tell a paraphrase from an invention, and it cannot see a value that
+// was dropped. It is a floor under model-driven conversion, which is highest
+// fidelity for layout and lowest for exact values (issue #31).
+//
+// Plain Node, no dependencies, safe to copy: `.agents/skills/` is the owner's.
+
+import { readFileSync } from "node:fs";
+
+const [, , extractionPath, documentPath] = process.argv;
+if (!extractionPath || !documentPath) {
+  console.error("usage: node verify.mjs <extraction.txt> <document.md>");
+  process.exit(2);
+}
+
+const fold = (s) => s.toLowerCase().replace(/\s+/g, " ");
+
+const extraction = fold(readFileSync(extractionPath, "utf8"));
+const raw = readFileSync(documentPath, "utf8");
+
+// Body only: frontmatter is the agent's own words by design (title,
+// description, ids). Footnote labels and definition prefixes are ids too.
+const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, "").replace(/\[\^[^\]]+\]:?/g, " ");
+
+const tokens = new Set();
+for (const m of body.matchAll(/\d[\d,.:/-]*\d|\d/g)) tokens.add(m[0]);
+for (const m of body.matchAll(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b/g)) tokens.add(m[0]);
+
+const missing = [...tokens].filter((t) => !extraction.includes(fold(t))).sort();
+for (const t of missing) console.log(t);
+process.exit(missing.length === 0 ? 0 : 1);

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

@@ -2,54 +2,26 @@
 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: "2.1.0"
+  version: "3.0.0"
 ---
 
 # Format checker
 
-`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.
+`pnpm check` runs `check.mjs`. The rules it holds the record to are the ones in
+`AGENTS.md` → "Writing knowledge"; this file says only what that section does
+not, which is how to relate to the program.
 
-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; the
-  site contains no content files.
-
-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.
+- **It is generated, and it is the same rule set** `ksor build` and
+  `ksor ingest` run, so the three can never disagree about a well-formed
+  record. Do not edit it: `ksor init` writes it and `ksor migrate` rewrites both
+  copies when you upgrade, so an edit is overwritten rather than kept. It
+  reports and never rewrites a file.
+- **Obey the printed fix literally.** Every refusal prints where, the rule's
+  slug (`problem: ksor-…`), why the rule exists, and the fix. If the fix does
+  not resolve the problem, that is a bug worth reporting to ksor.
+- **If its refusals contradict `AGENTS.md`, the checker is older than the
+  record**: upgrade `@panaversity/ksor` and re-run `ksor migrate`. Never "fix"
+  the record by undoing what a migration wrote.
+- **When you edit any skill under `.agents/skills/`, re-copy it to
+  `.claude/skills/`** — the checker holds the two trees byte-identical in both
+  directions.

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

@@ -11971,6 +11971,7 @@ function changedFields(before, after) {
 const CONTROL_FILES = [
 	"instance.md",
 	".ksor/governance.yaml",
+	".ksor/people.yaml",
 	".ksor/takedowns.yaml"
 ];
 /** Files the operating system writes behind the author's back: ignored, never reported. */
@@ -13551,6 +13552,7 @@ const lockSchema = object({
 	drafts: _enum(["hidden", "shown"]),
 	instance_sha256: hex64,
 	policy_sha256: hex64,
+	people_sha256: hex64,
 	ledger_sha256: hex64,
 	ledger_entries: array(object({
 		id: string().min(1),
@@ -13745,6 +13747,7 @@ const INPUTS = [
 	"knowledge",
 	"instance.md",
 	".ksor/governance.yaml",
+	".ksor/people.yaml",
 	".ksor/takedowns.yaml"
 ];
 function gitFacts(root) {

package/templates/scaffold/.claude/skills/intake-interview/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: intake-interview
-description: The first conversation with the owner of this Knowledge System of Record — seven questions that define what it is authoritative for, who may read it and who may approve it, then write instance.md together. Use when the owner asks to set up, configure, or "get started with" this project, when instance.md still contains its scaffold placeholder text, or when the scope of the corpus is unclear.
+description: The first conversation with the owner of this Knowledge System of Record — three questions that define what it is authoritative for, who may read it and who may approve it, then write instance.md together. Use when the owner asks to set up, configure, or "get started with" this project, when instance.md still contains its scaffold placeholder text, or when the scope of the corpus is unclear.
 metadata:
-  version: "1.5.0"
+  version: "1.6.0"
 ---
 
 # Intake interview
@@ -123,9 +123,10 @@ never an email address.
   Leave `name:` and `toolchain:` alone. One block is added here only when
   the owner stands up the served MCP rung — `database:`/`embedding:`/
   `retrieval:` (see `AGENTS.md` → "Serving to agents"; that is a later
-  climb, not part of this interview). The strictness answer from question 5
-  is the intent behind the `retrieval.vector_floor` on that climb, measured
-  by `ksor calibrate` — capture it in the prose now so it is ready.
+  climb, not part of this interview). The `declines` default above (or the owner's
+  correction to it) is the intent behind the `retrieval.vector_floor` on that
+  climb, measured by `ksor calibrate` — capture it in the prose now so it is
+  ready.
 - Write `.ksor/governance.yaml` from question 3: `version: "0.1"`,
   the `audiences:` registry if there is one, and the two authority sets with
   real actors. That file is the root of authority — every approval, every
@@ -134,12 +135,19 @@ never an email address.
   document is still in `knowledge/`.** Those five are approved by it, so a
   policy rewritten without it refuses the next build by name
   (`ksor-approver-unauthorised`). It leaves when the last sample does.
+- **Re-attribute what `human:you` already did.** If any document carries
+  `human:you` as its approver, generator or deprecator — the hello-world
+  tutorial's own document does — rewrite those acts to the owner's handle in
+  the SAME change that retires the placeholder from the policy. It is the same
+  person. A policy that stops naming `human:you` beside a document that still
+  cites it turns a green record red (`ksor-approver-unauthorised`), and the
+  owner's first act after being interviewed should not be a refusal.
 - Write `.ksor/people.yaml` from question 3: `version: "0.1"` and a `people:`
   MAP from each actor to its natural name — `"human:bashiraziz": Bashir Aziz`.
   Keyed by the actor exactly as the record stores it, quoted because it
   contains a colon. Nothing else — the site looks the actor up at render time,
   so pages read "Owner · Bashir Aziz" instead of "Owner · human:bashiraziz". Every skill that records a governance
-  act (this one, add-sources for `verified:` entries, `ksor takedown` for
+  act (this one, add-sources when it names a `ksor.owner`, `ksor takedown` for
   withdrawals) asks the owner for a natural name whenever it is about to write
   an actor that isn't in `people.yaml` yet — the owner is the only source of a
   display name, never a convention-based guess.
@@ -162,7 +170,7 @@ never an email address.
   the new title and refuses anything the profile does not accept.
 - Restart `pnpm dev` afterwards so the site picks the new title up, and
   show the owner their name on the page.
-- Offer to capture the source list from question 4 as the first real
-  documents (the add-sources skill takes it from there).
+- Offer to start on the owner's own documents: the add-sources skill takes
+  whatever material they have from there.
 - Read the result back to the owner and get an explicit yes before
   finishing. Their words, tightened — never your invention.

package/templates/scaffold/AGENTS.md

@@ -118,7 +118,15 @@ text-embedding-3-small`, `dim: 1536`, key in `OPENAI_API_KEY` — and each
    Turning it on is step 4, AFTER the record is serving.
 
 2. **Get the database — your agent can do this one.** `.mcp.json` at the repo
-   root declares the MCP servers this project may reach, and the first is Neon.
+   root declares the MCP servers this project may reach. It ships with two:
+   `Neon`, which provisions the Postgres this step needs, and
+   `agentfactory-system-of-record`, a read-only KSoR record Panaversity operates
+   as an example of the surface being built here — not this project's record,
+   and not needed by anything below. Either can be deleted; the file is the
+   adopter's.
+
+   The Neon server acts on the whole Neon ACCOUNT, not on one database: it can
+   create and delete projects and branches. Show the plan before running it.
    With it connected, ask:
 
    > Using the Neon MCP server, create a project called `<your-record>` and
@@ -793,9 +801,9 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   quiz had every correct answer in the same position across 451 questions.
 
   A **presentation** is slides the record owns. Ask your coding agent for one
-  rather than writing it by hand — `make slides for knowledge/<path>.md` runs
-  the `make-slides` skill, which reads the document, writes the deck, checks
-  every claim back against it, and tells you what it left out:
+  rather than writing it by hand: it reads the document whole, writes the
+  deck, checks every claim and every number back against the document, and
+  tells you what it left out because the document did not support it:
 
   ```yaml
   slides:
@@ -910,6 +918,11 @@ SAMEORIGIN`, which forbids any other site from framing them, and a browser
 - Copy load-bearing values (numbers, thresholds, dates) exactly from their
   source, name the source in `sources`, and cite it from the claim with a GFM
   footnote whose label is that source's `id`.
+- **The record says only what its source says.** A gap is an open question
+  written into the document — never filled from general knowledge — and two
+  sources that disagree stay two cited statements: flag the disagreement to
+  the owner rather than choosing. That boundary is the product; a record that
+  quietly knows more than its sources is a chatbot with a sidebar.
 
 ### Structuring the record
 
@@ -932,12 +945,10 @@ SAMEORIGIN`, which forbids any other site from framing them, and a browser
 
 - `.agents/skills/intake-interview/` — first run: interview the owner and
   write `instance.md` together.
-- `.agents/skills/add-sources/` — turn source material (documents, pages,
-  notes) into governed knowledge.
-- `.agents/skills/make-slides/` — generate a presentation from one document
-  and attach it, so it renders on that document's page.
-- `.agents/skills/make-summary/` — write a document's summary and attach it,
-  so it renders as a second tab on that document's page.
+- `.agents/skills/add-sources/` — turn what the owner has into governed
+  knowledge: a document, a page, notes, or what they tell you that nobody
+  wrote down. Converts files with a verified extraction, interviews a person
+  for the rest, and ends with the owner's approval.
 - `.agents/skills/format-checker/` — the rules above, as a program;
   `pnpm check` runs it and its errors explain how to fix themselves.