@panaversity/ksor 0.0.40 → 0.0.41

package/templates/scaffold/.agents/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 — six questions that define what it is authoritative for and who may read 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 — 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.
 metadata:
-  version: "1.3.0"
+  version: "1.5.0"
 ---
 
 # Intake interview
@@ -12,7 +12,7 @@ prose IS the agent surface's system prompt (`ksor serve` wires it into the MCP
 server's instructions). Do not draft it from guesses — interview the owner, one
 question at a time, and write down what they actually say.
 
-## The six questions
+## The first six questions
 
 Ask these one at a time; follow up until each answer is concrete enough to
 act on:
@@ -31,33 +31,71 @@ act on:
    should it decline? ('Not in this corpus' is a correct answer here —
    confirm the owner wants that behavior and where they want it softened.)"
 6. **Audiences** — "Does every reader of this record see every document? If
-   not, what are the audiences, from most public to most restricted?" A yes
-   is the common answer and the whole answer: write no `audiences:` key and
-   nothing about the project changes. A list means writing it into
-   `instance.md`'s frontmatter — ordered least- to most-restricted with
-   `public` first, plus `default_visibility:` naming the audience a document
-   takes when it says nothing (there is no safe guess, so the checker
-   requires it). Tell the owner what the key does and does not do:
-   documents carry `visibility:` and builds are made per audience, but
-   anyone who can clone the repository reads everything in it — if someone
-   must not read a document and can clone, that document belongs in a
-   different repository.
+   not, what are the audiences?" A yes is the common answer and the whole
+   answer: register none, and every document says `ksor.audience: [public]`.
+   Anything else means registering each audience in
+   `.ksor/governance.yaml` under `audiences:`, with a one-line
+   `description:` of who is in it — `public` is reserved and never
+   registered. There is no ranking and no default: a document lists the
+   audiences that may read it, a reader holds a list that always includes
+   `public`, and the document is visible when the two lists OVERLAP. Tell
+   the owner what this does and does not do: builds are made per audience,
+   but anyone who can clone the repository reads everything in it — if
+   someone must not read a document and can clone, that document belongs in
+   a different repository.
+
+## Then ask the seventh, because a policy cannot be guessed
+
+7. **Authority** — "Who may approve a document for publication, and who may
+   withdraw one?" Names, not roles-in-the-abstract: they become
+   `approval_authorities` and `takedown_authorities` in
+   `.ksor/governance.yaml`, and the checker refuses an approval or a
+   takedown by anyone the policy does not name. The scaffold ships
+   `human:you` in both — a placeholder that must not survive this
+   conversation. An actor is `human:<handle>`, `process:<name>` or
+   `<producer>/<version>`; handles are published with the record, so use the
+   handle the owner would put in a commit, never an email address.
 
 ## Then write
 
-- Rewrite `instance.md`'s body from the answers: first the `# H1` — the
-  record's **display title**, the human name every page will lead with
-  ("Acme Operations Handbook", not the slug) — then the authority sentence,
-  boundary, audience, and strictness — plain prose, written for a reader
-  who must act on it. Leave the identity frontmatter keys alone; two things
-  are written there when they apply: an audience model from question 6, as
-  `audiences:` (a list) and `default_visibility:` (`pnpm check` holds the
-  record to it from that moment on); and — only when the owner stands up the
-  served MCP rung — the `database:`/`embedding:`/`retrieval:` blocks (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.
+- Rewrite `instance.md` from the answers. `title:` is the record's
+  **display title**, the human name every page leads with ("Acme Operations
+  Handbook", not the slug); `description:` is one sentence, and it seeds
+  `llms.txt` and the MCP discovery document; the BODY is the authority
+  sentence, boundary, audience and strictness — plain prose, handed in full
+  to every connecting agent as the MCP server's instructions, so write it
+  for a reader who must act on it. There is no `# H1`: the title is a key.
+  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.
+- Write `.ksor/governance.yaml` from questions 6 and 7: `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
+  deprecation and every ledger entry is checked against it. **Keep
+  `ksor-starter/KSOR-STAMP-VERSION` in `approval_authorities` while any starter
+  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.
+- **Offer to start replacing the starter documents — they are already
+  published.** All five ship `status: stable`, approved by
+  `ksor-starter/KSOR-STAMP-VERSION`, so the site and `llms.txt` carry them from
+  the first build. They describe KSoR itself rather than the owner's
+  organisation. Say it plainly: "Five sample documents about KSoR are published
+  on your record right now. The tool that wrote them approved them — nobody has
+  reviewed them, which is what the _unverified_ tier on each page says. Shall we
+  start replacing them with yours?" Replacing means deleting the sample and
+  writing a real document at `status: draft`; the owner approves it afterwards,
+  and that act is theirs. When the last sample is gone, delete
+  `ksor-starter/KSOR-STAMP-VERSION` from `approval_authorities` in the same
+  change — nothing of theirs should be approved by a tool. Never record an
+  approval nobody gave, and never write a `verified` entry: the approval is not
+  a review, and inventing one would retire the tier that exists to say nobody
+  has checked this.
+- Run `ksor build` afterwards: it regenerates every folder's `index.md` from
+  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

package/templates/scaffold/.agents/skills/make-slides/SKILL.md

@@ -38,7 +38,8 @@ Read `<doc>.md` completely before writing anything. Note as you go:
 - **the numbers** — thresholds, deadlines, limits, and their units
 - **the cases** — what happens in each situation it names
 - **the boundary** — what it explicitly does NOT cover
-- **its governance** — `owner`, `effective`, `status` from the frontmatter
+- **its governance** — `status`, `ksor.owner` and `ksor.effective_from` from
+  the frontmatter
 
 If the document carries `<doc>.summary.md`, read that too: it is a reviewed
 compression of the same thing, and it tells you what the author thought was
@@ -108,16 +109,17 @@ the session it was made for, because the next presenter trusts it.
 ## 4 · Verify it
 
 ```sh
-pnpm check     # refuses an orphan, frontmatter, or a malformed deck
-pnpm dev       # look at the page — the deck renders at the end
+pnpm check     # refuses an orphan deck
+pnpm dev       # look at the page — the deck renders after the introduction,
+               # immediately before the first `##` section
 ```
 
-`pnpm build` refuses:
+`pnpm build` refuses — the deck's own shape is checked in the site build, not
+by `pnpm check`:
 
 - `ksor-slides-empty` — neither `deck:` nor `slides.url:`; nothing to show
 - `ksor-slides-two-sources` — both, so nothing says which one governs
 - `ksor-attachment-orphan` — no `<doc>.md` beside it
-- `ksor-attachment-frontmatter` — an attachment carries none of its own
 
 ## 5 · Tell the owner what you did
 

package/templates/scaffold/.agents/skills/make-summary/SKILL.md

@@ -2,7 +2,7 @@
 name: make-summary
 description: Write the summary of a document and attach it, so it renders as a second tab on that document's page. Use when the owner says "summarise X", "make a summary for this", "add summaries to the record", "give me the short version", or asks for a TL;DR, an abstract or a précis of a governed document.
 metadata:
-  version: "1.0.0"
+  version: "1.1.0"
 ---
 
 # Writing the summary of a document
@@ -48,17 +48,24 @@ Read `<doc>.md` completely before writing anything. Note as you go:
 - **the numbers** — thresholds, deadlines, limits, and their units
 - **each `##` section** — and the one thing it is there to say
 - **the boundary** — what the document explicitly does NOT cover
-- **its governance** — `owner`, `effective`, `status` from the frontmatter
+- **its governance** — `status`, `ksor.owner` and `ksor.effective_from` from
+  the frontmatter
 
 If the document already carries `<doc>.slides.yaml`, read it: it is a reviewed
 compression of the same thing, and the two must not disagree.
 
 ## 2 · Write the summary
 
-Write `<doc>.summary.md` beside the document. **No frontmatter** — an
-attachment carries none, and the checker refuses one:
+Write `<doc>.summary.md` beside the document. Its frontmatter is exactly one
+key and the checker refuses any other — a summary inherits its parent's
+audience, status and takedown, and a second key there would claim governance a
+non-document cannot carry:
 
 ```markdown
+---
+type: Summary
+---
+
 The lead: what this document settles, in one or two sentences, in the
 document's own words. **Bold the thing a reader must not misremember.**
 
@@ -107,14 +114,14 @@ document, not before it.
 ## 4 · Verify it
 
 ```sh
-pnpm check     # refuses an orphan or an attachment carrying frontmatter
+pnpm check     # refuses an orphan, or frontmatter that is not exactly `type: Summary`
 pnpm dev       # open the page — a Summary tab appears beside Document
 ```
 
 The build refuses:
 
 - `ksor-attachment-orphan` — no `<doc>.md` beside it
-- `ksor-attachment-frontmatter` — an attachment carries none of its own
+- `ksor-attachment-frontmatter` — anything but exactly `type: Summary`
 
 If no Summary tab appears, the file name is wrong: it must be exactly
 `<doc>.summary.md`, matching the document's own name.

package/templates/scaffold/.claude/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/.claude/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.