@panaversity/ksor 0.0.55 → 0.0.56

package/CHANGELOG.md

@@ -1,5 +1,195 @@
 # @panaversity/ksor
 
+## 0.0.56
+
+### Patch Changes
+
+- bf35e2f: `add-sources` 2.0.0: a file or a person, one skill — with a check the agent
+  runs instead of a rule it is asked to follow.
+
+  Two issues asked for two paths into the record. #31: an owner with a folder of
+  PDFs had no path — the skill stated the rules and converted nothing. #50: an
+  owner whose knowledge is only in their head had no path — the interview scoped
+  the record and stopped, leaving `knowledge/` full of samples about KSoR.
+
+  **They are one skill, not two.** The record draws no line between the kinds:
+  an interview attestation in `sources[].resource` passes `ksor build` today,
+  the fidelity rules read the same for both, and a real owner has BOTH — the
+  policy PDF and the exception everyone knows that the PDF never mentions. So
+  the person step runs after every file: "what does this not cover?" is the
+  question that finds the pages nobody wrote. A sibling skill would have made
+  the agent choose before it knew, and #50's own three-way trigger collision
+  vanishes.
+
+  **The source is a file.** Extract first, into a scratch file outside
+  `knowledge/` — the skill names the extractor per format (`pdftotext`,
+  `pandoc`, macOS `textutil`, `markitdown`) and what to do with none on `PATH`:
+  read the file directly and SAY the verification that follows is weaker. An
+  empty extraction is a scanned image, and the skill stops and tells the owner
+  rather than OCR and hope. Then decide the shape of the record, convert to
+  CommonMark a person would have written, name the source precisely, and run
+  the shipped check:
+
+  ```
+  node .agents/skills/add-sources/verify.mjs /tmp/in.txt knowledge/<path>.md
+  ```
+
+  `verify.mjs` — plain Node, no dependencies, the owner's to keep — lists every
+  number, date, threshold, code and capitalised name in the document's body that
+  does not appear in the extraction, case-folded and whitespace-collapsed.
+  Frontmatter and footnote ids are exempt, because they are the agent's words by
+  design. It is a floor, and says so: a value that passes was in the source; it
+  cannot see a value that was dropped, and it cannot tell a paraphrase from an
+  invention. Model-driven conversion is highest-fidelity for layout and
+  lowest for exact values, and this is the mechanical half of "copy load-bearing
+  values exactly".
+
+  **The source is a person.** Ask one question at a time in their words — who
+  triggers it, the steps, who approves and at what threshold, what goes wrong,
+  the exception — until someone who was not in the room could act on it. Draft
+  as the record, not a transcript; anything unconfirmed is an `Open question:`
+  line, never prose. The attestation goes in `sources` (who, role, instant,
+  conducted by) — there is no `provenance:` key, and no transcript is kept.
+  Two people describing one process differently stay two cited statements.
+
+  **Both end the same way, and the ending is new.** Read it back on `pnpm dev`,
+  then ask the owner to approve and write down what they said. A draft reaches
+  no machine surface, so a skill that stopped at the draft left every `llms.txt`
+  and every door empty — found on the journey walk: `1 document(s), 0 admitted`.
+
+  The rules that were restated here (placement, frontmatter, audience,
+  deprecation) now point at the emitted AGENTS.md instead. The trigger test that
+  asserted "no skill claims dictated knowledge" flips: add-sources claims it by
+  name, and no other skill may. Eleven cases hold `verify.mjs` to what it does
+  and, in three of them, to what it does not claim.
+
+- 73530e6: Prune the scaffold's skills to the three that make a record, and fix the two
+  seams every adopter hits on the way to one.
+
+  **Removed: `make-slides` and `make-summary`.** They were 45% of all shipped
+  skill text and 21.6% identical to each other — their own commit says
+  "make-summary is make-slides' discipline applied to prose". A companion is
+  downstream of a record existing and invisible to the agent surface (no route,
+  no `llms.txt` line, no MCP node); no fixture and no tutorial ever fired either;
+  and neither was ever shown to beat its absence, which is the bar AGENTS.md sets
+  for keeping a skill at all. Their one real rule — a card may only say what its
+  document says — already lives in the emitted AGENTS.md, and the site renders
+  companions exactly as before. Verified: the emitted checker passes with both
+  gone. `format-checker/SKILL.md` is cut to what AGENTS.md does not say; the
+  program it names is unchanged.
+
+  **Fixed: `intake-interview` was contradicting itself in its trigger.** The
+  always-resident description promised "seven questions"; the body has asked
+  three since 2026-08-26. The body handed off to "question 4" and "question 5",
+  neither of which exists, and claimed `add-sources` writes `verified:` entries —
+  nothing does. 1.6.0 says three, hands off to add-sources with whatever material
+  the owner has, and drops the false claim.
+
+  **Fixed: the recommended path turned a green record red.** Walked on the
+  published package:
+
+  - The README said run the interview, then "delete each starter as your own
+    knowledge arrives". Delete the five first and the build refuses
+    `ksor-record-empty` and writes nothing — a slug named by no document an
+    adopter reads. The README now says to write and approve one document of
+    your own before the last starter goes, and names the refusal.
+  - The hello-world tutorial approves as `human:you`. The interview then retires
+    `human:you` from the policy, and the tutorial's own document — still approved
+    by an actor the policy no longer names — refuses `ksor-approver-unauthorised`.
+    The interview now re-attributes every act recorded under the placeholder to
+    the owner's handle in the same change: it is the same person.
+
+  **Consolidated:** "the record says only what its source says — a gap is an
+  open question, never filled from general knowledge" lived only inside
+  `add-sources`; it is now stated once in the emitted AGENTS.md where every
+  other writing rule is.
+
+  Two deterministic gates hold all of this: a skill-consistency lint (a trigger's
+  question count matches its body; every "question N" resolves; every refusal
+  slug a document names is one the product raises; every skill a document names
+  ships) and a journey walk against the built CLI (interview → one draft →
+  approve → delete starters → retire the starter actor, plus the exact state
+  each refusal fires on). Every lint assertion was mutation-tested.
+
+  Found by four independent reviews of the plan to build a system of record,
+  before building any of it.
+
+- ab6a3ed: The agent tier: a shipped skill, run by a real coding agent, with the skill
+  and without it — the comparison AGENTS.md has always demanded and nothing had
+  ever run (issue #30).
+
+  `pnpm test:agent` scaffolds a fresh record, installs it, drops a real two-page
+  PDF in `src/`, and hands `claude -p` the prompt tutorial 2 hands the reader.
+  Once with `add-sources` present, once with it removed. What the agent leaves
+  behind is graded, and the split is the Testing contract's own: deterministic
+  behavioural graders GATE the with-skill arm — exactly one new document, under
+  `finance/`; `.ksor/*` and `instance.md` untouched; the record builds; `status:
+draft`, `sources` present, no `id:`/`name:`; page furniture gone; every
+  number, date and name in the body found in the extraction by the shipped
+  `verify.mjs`. Cost, turns, duration and the baseline arm are REPORTED, so the
+  delta is visible and a skill that stops winning is seen.
+
+  "Checker passes" is deliberately not a grader: while this was being designed a
+  baseline run passed the checker by hand-authoring `index.md` and editing
+  `.ksor/people.yaml` — the worse behaviour scoring better. Files touched is the
+  discriminating assertion.
+
+  It spends model tokens, so it is gated like the database tier: on
+  `ANTHROPIC_API_KEY` in CI (a repository secret the owner has not yet added; the
+  tier runs and reports itself skipped until then) or a logged-in `claude`
+  locally, pins a mid-tier model by default (a one-word reply on the default
+  model measured $0.25), and runs from `skill-evals.yml` on push to main and by
+  hand — never per pull request.
+
+  What it cannot measure is written in the suite rather than implied: a
+  conversational skill needs a scripted owner, "reads as a finished page" needs
+  a browser, and the adopter's own model is whatever they run.
+
+  Decision 31 records the three choices this week made about the skill surface —
+  pruned to three, one skill for a file and a person, and this harness shape
+  over the Python trigger script that was proposed and measured wanting.
+
+- c34cc3a: Tutorial 2, _Make it yours_: the walk from hello world's record to one that is
+  only the owner's — every output run and pasted as it appeared.
+
+  The intake interview and what it does to the placeholder approver; one policy
+  brought in from a real PDF, with the shipped check catching the one number the
+  conversion got wrong; one procedure that only ever lived in someone's head,
+  written with the thing they were not sure of as an open question rather than
+  prose; the read-back on the site and the approval act; then the samples go and
+  the tool that approved them leaves the policy. Two refusals do work on the way,
+  and the tutorial says exactly which state each fires on.
+
+  The prompt-accounting test now covers both tutorials from one table, so a new
+  prompt in either fails until someone names the skill that answers it. Only that
+  test changes under `packages/`; nothing an adopter installs behaves differently.
+
+- 87a3542: Correct a claim the tutorial made about `build_id`, and guard the general rule.
+
+  `buildIdOf` hashes `ksor_version` along with the record — deliberately, because
+  "what produced this" is part of what a publication is. So a captured `build_id`
+  is correct for exactly one release, and the sentence 0.0.54's tutorial fix added
+  — "Your timestamp will differ; the `build_id` will not" — was already false when
+  0.0.55 published it. A reader on any later ksor sees a hash that does not match
+  theirs and nothing saying why.
+
+  Found by walking the published package rather than by reading the diff: the same
+  practice that caught the tutorial being uncompletable caught the correction being
+  wrong.
+
+  The tutorial now says the id carries the toolchain, names the version its
+  outputs were captured on, and points at the reproducibility a reader can
+  actually check — run `ksor build` twice on one tree and the id is identical.
+  Both captured blocks are re-taken from a 0.0.55 walk.
+
+  A guard in `docs-truth.integration.test.ts` holds the general rule rather than
+  the sentence: a document printing a concrete `build_id` must say what moves one,
+  within 700 characters of the id. It is PROXIMITY rather than presence — the
+  first version asked whether "toolchain" appeared anywhere in the file, the file
+  already used the word once for an unrelated reason, and removing the caveat left
+  it green. Caught by mutation, and the tightened version immediately found a
+  second uncaveated id in the same document.
+
 ## 0.0.55
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.55",
+  "version": "0.0.56",
   "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/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/.agents/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/.agents/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/.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 — 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.