@panaversity/ksor 0.0.39 → 0.0.41

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 — 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/.claude/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/.claude/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/.github/workflows/validate.yml

@@ -16,8 +16,16 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          # Full history, and the checker below NEEDS it: the takedown ledger
+          # is append-only, and the committed build.lock.json cannot prove that
+          # on its own — it travels in this very pull request and can be edited
+          # in the same commit that deletes a denial. Git history is the
+          # baseline that is not in the change. On a shallow clone the checker
+          # says so (ksor-ledger-unverifiable) and falls back to the lock;
+          # `ksor build` refuses that state outright.
+          fetch-depth: 0
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: "24"
-      # The checker is dependency-free Node — no install step needed.
+      # The checker is self-contained Node (generated by ksor) — no install step needed.
       - run: node .agents/skills/format-checker/check.mjs

package/templates/scaffold/.ksor/governance.yaml

@@ -0,0 +1,17 @@
+# The Governance Policy: who has authority over this record. The intake
+# interview replaces `human:you` with real handles. `public` is implicit;
+# register a restricted audience here before any document names it:
+#   audiences:
+#     internal:
+#       description: Employees
+version: "0.1"
+approval_authorities:
+  # `ksor-starter/...` approved the five sample documents it shipped, so a fresh
+  # record PUBLISHES on the first build instead of admitting nothing. It is a
+  # producer, not a person: it cannot be mistaken for a human who reviewed
+  # anything, and the trust tier stays `unverified`, which is the honest word
+  # for "nobody has checked this". Delete this actor once the samples are gone
+  # — nothing of yours should ever be approved by a tool.
+  - actors: [human:you, ksor-starter/KSOR-STAMP-VERSION]
+takedown_authorities:
+  actors: [human:you]