unknown-knowledge 2.1.0

package/payload/templates/decisions/trust-graduation.yaml

@@ -0,0 +1,120 @@
+# Decisions-entry template — graduating a change category (UCS-1155).
+#
+# A graduation narrows moderation on ONE CHANGE CATEGORY from 100% inspection to
+# sampling. Copy this file to decisions/entries/<id>-<slug>.yaml, fill it, and
+# open ONE PR carrying the entry and — if the category is not yet declared — the
+# row that declares it in decisions/_registries/graduation-categories.yaml.
+#
+# Autonomy is PER CATEGORY, never per leaf. "L-000117 has been right ten times"
+# is not evidence about anything: the eleventh leaf is a different claim by a
+# different author. "Alias additions have been approved unmodified ten cycles
+# running" is evidence about a class of edit, which is why the category is the
+# unit and why a graduation names one.
+#
+# WHAT THE ENGINE CHECKS, AND WHAT IT DOES NOT. It checks that this entry is
+# well-formed, that the category it names is declared in the table, and that the
+# category is not permanently gated. It does NOT compute the approved-unmodified
+# count and does not decide whether the threshold was met — v1's analytics are
+# MANUAL. `observed-cycles` below is YOUR record of what you counted, written
+# down so a reviewer can weigh the judgment; no code asserts it. Do not read a
+# green validator as agreement that the bar was cleared.
+#
+# The two rules this entry exists to evidence:
+#
+#   REVOCATION IS AUTOMATIC ON ANY DEFECT. A single defect found in a graduated
+#   category revokes it — not "a serious defect", not "a pattern of defects".
+#   The whole warrant for sampling is that this class of change stopped
+#   producing surprises, and one surprise is the evidence that it has not.
+#   Record the revocation with templates/decisions/trust-revocation.yaml.
+#
+#   CITATION SPOT-CHECKS SURVIVE EVERY GRADUATION. The sampling plan keeps
+#   citation spot-checks at every trust level, including the most graduated. A
+#   citation is a claim about the world that the store cannot check for itself,
+#   so no streak of clean mechanical edits is evidence that the citations are
+#   sound — those are different questions, and graduation only ever answers the
+#   first.
+#
+# The `id` and `date` placeholders below are DELIBERATELY not valid, so this
+# file fails validation until a steward fills them — pasting the template
+# unedited must never produce a Decisions entry, or moderation would narrow on a
+# rationale nobody wrote.
+#
+# Those two are the ones that fail on their SHAPE, but they are not the whole
+# edit. Every <angle-bracket> placeholder must be replaced before this entry
+# says anything true, and how each unfilled one fails differs — which is worth
+# knowing, because the finding you get is not always the mistake you made:
+#
+#   - `graduation.category` is pattern-checked (lowercase kebab), so an
+#     unfilled `<category-name>` is a KK-02 `pattern-mismatch` at EXIT 2, not a
+#     graduation finding. The store fails to load rather than validating with
+#     findings, so the graduation checks never run at all.
+#   - the PROSE fields (context, decision, consequences, title, deciders,
+#     provenance) are free strings. Nothing rejects them, so an unfilled one
+#     validates green while saying nothing true. Those are the dangerous ones:
+#     the only check on them is a reader.
+#
+# The full inventory:
+#
+#   id                    the provisional D-YYYY-MM-DD-<slug> (schema-rejected)
+#   date                  the real date (schema-rejected)
+#   title                 <category>
+#   deciders              <steward>
+#   context               the whole prose block — the count and where you read it
+#   decision              <category>, <rate>
+#   consequences          the whole prose block
+#   graduation.category   <category-name> — must match a row in the table
+#   graduation.observed-cycles   your actual count, not 0
+#   provenance.author     <steward-or-agent>
+#   provenance.skill-version     <skill@version>
+schema-version: 1
+entries:
+  - id: D-YYYY-MM-DD-graduate-example-category
+    title: "Graduate <category> to sampling"
+    # `trust` — this entry moves the system's own trust boundary, which is what
+    # the third store governs (PRD §3: rationale, ADR-style records, trust
+    # graduations).
+    category: trust
+    status: proposed
+    date: "YYYY-MM-DD"
+    deciders: [<steward>]
+    # THE EVIDENCE. Name the category, the count of consecutive approved-
+    # unmodified cycles you observed, and where you read it (reflect records
+    # per-item approval outcomes by category — that is the observable basis).
+    # "It feels safe by now" is the case this refuses: the count is what makes
+    # the judgment reviewable by someone who was not in the room.
+    context: >-
+      <Which category, how many consecutive approved-unmodified cycles it has
+      run, and where those cycles are recorded. Note anything that would make
+      the streak misleading — a quiet period with few changes is not the same
+      evidence as a busy one.>
+    # What narrows, and to what. Say the sampling rate plainly: "graduated" is
+    # not a synonym for "unreviewed", and the entry should say what inspection
+    # remains.
+    decision: >-
+      <Graduate <category> from full inspection to sampling at <rate>. Citation
+      spot-checks continue at this level, as at every level.>
+    # Say the revocation trigger out loud. A reader six months from now needs to
+    # know that this narrowing is conditional and how it ends.
+    consequences: >-
+      <What is no longer inspected on every change, and what still is. Any
+      defect found in this category revokes this graduation automatically —
+      recorded as its own entry, returning the category to full inspection.>
+    supersedes: []
+    # The typed block the validator reads. `category` must name a row in
+    # decisions/_registries/graduation-categories.yaml, and that row must not be
+    # permanently gated — a gated category cannot graduate however strong the
+    # streak, because the gate is about the KIND of judgment the change needs.
+    graduation:
+      action: graduate
+      category: <category-name>
+      # Your manual count. Recorded, not computed (see above).
+      observed-cycles: 0
+    # Who wrote this entry and with which skill revision. Not decoration: if a
+    # graduation later proves to have been drafted by a bad skill vintage, this
+    # is what makes every entry from that vintage findable rather than guessed
+    # at.
+    provenance:
+      author: <steward-or-agent>
+      skill-version: <skill@version>
+    relates-to:
+      decisions: []

package/payload/templates/decisions/trust-revocation.yaml

@@ -0,0 +1,106 @@
+# Decisions-entry template — revoking a graduation (UCS-1155).
+#
+# A revocation returns ONE CHANGE CATEGORY from sampling to 100% inspection.
+# Copy this file to decisions/entries/<id>-<slug>.yaml, fill it, and open it as
+# an ordinary PR.
+#
+# REVOCATION IS AUTOMATIC ON ANY DEFECT, and "automatic" is meant literally:
+# the trigger is a defect found in a graduated category, not a judgment that the
+# defect was bad enough. There is no severity threshold to argue about and no
+# discretion to exercise. The warrant for sampling a category was that it had
+# stopped producing surprises; one surprise is the evidence that it has not, and
+# the response is mechanical so that it cannot be talked out of.
+#
+# This is deliberately the CHEAPEST entry in the store to write. Narrowing
+# inspection takes a counted streak and a written rationale; restoring it takes
+# noticing one defect. That asymmetry is the design — if revoking were as
+# laborious as graduating, the laborious thing would quietly not get done, and
+# the trust boundary would only ever move one way.
+#
+# Revoking is always legitimate. The validator refuses a graduation for a
+# permanently gated category, but never a revocation: a revocation only narrows
+# autonomy, and refusing to record one would be refusing the safe direction.
+#
+# After revoking, the category returns to full inspection and its streak starts
+# again from zero. A previously graduated category is not owed a shorter road
+# back — the earlier streak was evidence about a period that has now ended.
+#
+# The `id` and `date` placeholders below are DELIBERATELY not valid, so this
+# file fails validation until a steward fills them — pasting the template
+# unedited must never produce a Decisions entry.
+#
+# Those two are not the whole edit. Every <angle-bracket> placeholder must be
+# replaced before this entry says anything true, and how each unfilled one
+# fails differs — which is worth knowing, because the finding you get is not
+# always the mistake you made:
+#
+#   - `graduation.category` is pattern-checked (lowercase kebab) and
+#     `graduation.revokes` is pattern-checked (D-NNN), so leaving either
+#     unfilled is a KK-02 `pattern-mismatch` at EXIT 2. The store fails to load
+#     rather than validating with findings, so the graduation checks never run.
+#   - the PROSE fields (context, decision, consequences, title, deciders,
+#     defect, provenance) are free strings. Nothing rejects them, so an
+#     unfilled one validates green while saying nothing true. Those are the
+#     dangerous ones: the only check on them is a reader.
+#
+# The full inventory:
+#
+#   id                    the provisional D-YYYY-MM-DD-<slug> (schema-rejected)
+#   date                  the real date (schema-rejected)
+#   title                 <category>
+#   deciders              <steward>
+#   context               the whole prose block — the defect, and how it surfaced
+#   decision              <category>
+#   consequences          the whole prose block
+#   graduation.category   <category-name> — must match a row in the table
+#   graduation.revokes    D-NNN — the graduation being withdrawn. DELETE this
+#                         line if no graduation for the category exists (the
+#                         standing-position case); leaving `D-NNN` literal is an
+#                         unresolved ref, and omitting it when a graduation DOES
+#                         stand is a `disconnected-revocation` finding
+#   graduation.defect     <what went wrong>
+#   provenance.author     <steward-or-agent>
+#   provenance.skill-version     <skill@version>
+schema-version: 1
+entries:
+  - id: D-YYYY-MM-DD-revoke-example-category
+    title: "Revoke sampling for <category>"
+    # `trust` — like the graduation it withdraws, this entry moves the system's
+    # own trust boundary.
+    category: trust
+    status: proposed
+    date: "YYYY-MM-DD"
+    deciders: [<steward>]
+    # THE DEFECT. Name what went wrong concretely — the change, what was wrong
+    # with it, and how it was caught. This is the substance: a revocation whose
+    # context cannot name a defect is a revocation nobody can learn from, and
+    # the next graduation of this category will have nothing to have fixed.
+    context: >-
+      <Which defect was found, in which change, and how it surfaced — a
+      spot-check, a downstream correction, a reader's report. Name the graduation
+      entry this withdraws.>
+    decision: >-
+      <Revoke the graduation of <category>. The category returns to full
+      inspection immediately; its approved-unmodified streak restarts at zero.>
+    # What this obliges. A defect that reached the store under sampling may have
+    # company: say whether the material admitted while graduated needs a sweep.
+    consequences: >-
+      <What returns to full inspection, and whether changes admitted under
+      sampling need reviewing. If the defect suggests a bad skill revision, name
+      it — entry provenance makes the affected entries findable.>
+    supersedes: []
+    graduation:
+      action: revoke
+      category: <category-name>
+      # The graduation entry being withdrawn. Resolved like any other ref, so a
+      # revocation naming no graduation is an unresolved-ref error — the
+      # withdrawal and the thing withdrawn stay connected in the record.
+      revokes: D-NNN
+      # What went wrong, in one line. The machine-checkable half is that a
+      # revocation exists at all; this is the half a human reads.
+      defect: <what went wrong>
+    provenance:
+      author: <steward-or-agent>
+      skill-version: <skill@version>
+    relates-to:
+      decisions: []

package/payload/templates/knowledge/_catalog.yaml

@@ -0,0 +1,9 @@
+# knowledge/_catalog.yaml — navigational entry point (catalog -> rules -> leaves).
+# Each row names its leaf by ACCESSION id (L-NNNNNN) and locates it with `file`;
+# those are two independent facts, so moving a leaf between prefix-shard
+# directories updates `file` alone and invalidates no citation.
+# Empty seed: init copies it; the kb-build skill fills entries as cited leaves land.
+# Shape: payload/schemas/catalog.schema.json. schema-version evolves additively (§3.5).
+schema-version: 1
+store: knowledge
+entries: []

package/payload/templates/knowledge/_registries/anchor.yaml

@@ -0,0 +1,42 @@
+# The anchor registry — which truth anchor a leaf's claim answers to.
+#
+# THE VOCABULARY IS FIXED BY D-003, BUT THE FILE STILL SHIPS EMPTY. Those are
+# two different facts and both matter.
+#
+# Fixed: the three anchors ARE the kit's architecture (D-003 splits facts into
+# three stores by truth anchor — Ontology/artifact, Knowledge/world,
+# Decisions/team). A project that minted a fourth would be describing a store
+# this engine does not have, so unlike domains or form, this is not a vocabulary
+# to invent. Mint from the three below and no others.
+#
+# Empty anyway: every registry value must cite a Decisions entry that RESOLVES
+# (UCS-1148), and a freshly seeded repo's decisions store is empty by design
+# (D-001 — the repo is yours the moment it lands, and the kit does not write
+# entries into it). Shipping values citing the kit's own D-003 would seed every
+# client repo with a broken ref, and shipping them citing nothing would put a
+# vocabulary change in the store that nobody signed. So the bootstrap interview
+# mints these three the same way it mints everything else: this file plus one
+# Decisions entry of your own, recording that you adopted D-003's split.
+#
+# Flat vocabulary. Value shape: lowercase kebab. Mint exactly these:
+#
+#   values:
+#     - value: artifact
+#       gloss: The repo decides. The claim is checkable against code, config, or schema.
+#       warrant: <the leaf whose claim reads back to a source-of-truth pointer>
+#       decision: <your entry adopting the D-003 anchors>
+#       minted: "2026-07-07"
+#     - value: world
+#       gloss: An outside authority decides — a regulator, a vendor, a standard.
+#       warrant: <the leaf whose claim only a cited outside source can settle>
+#       decision: <your entry adopting the D-003 anchors>
+#       minted: "2026-07-07"
+#     - value: team
+#       gloss: The team decided. The claim is true because it was chosen, not discovered.
+#       warrant: <the leaf restating a team choice, which answers to the entry that made it>
+#       decision: <your entry adopting the D-003 anchors>
+#       minted: "2026-07-07"
+schema-version: 1
+store: knowledge
+registry: anchor
+values: []

package/payload/templates/knowledge/_registries/authority-tiers.yaml

@@ -0,0 +1,32 @@
+# The citation authority-tiers registry — how far a cited source can be trusted.
+#
+# Ships EMPTY. Which tiers a project recognizes is the project's own to mint: a
+# tier is a governed value, never an engine-shipped enum, because what counts as
+# authoritative is a judgement about a domain rather than a fact about software.
+# See protocol/registry-warrant.md.
+#
+# What the tier does TODAY: it is recorded and checked for membership, so every
+# citation says how far its source can be trusted rather than leaving a
+# regulator's text and a hallway conversation to read identically. Nothing in
+# the engine compares two tiers or resolves a conflict between citations yet —
+# automatic conflict ranking arrives with the resolution pipeline (UCS-1152).
+# Recording the tier now is what makes that possible: a tier nobody wrote down
+# cannot be ranked retroactively.
+#
+# Flat vocabulary. Value shape: lowercase kebab.
+#
+#   values:
+#     - value: primary
+#       gloss: The issuing body's own published text.
+#       warrant: 362.1 cites the Component Kit API reference, the vendor's own text.
+#       decision: D-014
+#       minted: "2026-07-07"
+#     - value: secondary
+#       gloss: Commentary on a primary source.
+#       warrant: 362.2 cites a community summary of those rules.
+#       decision: D-014
+#       minted: "2026-07-07"
+schema-version: 1
+store: knowledge
+registry: authority-tiers
+values: []

package/payload/templates/knowledge/_registries/domains.yaml

@@ -0,0 +1,43 @@
+# The hierarchical domains registry — the subject spine of the knowledge store.
+#
+# Ships EMPTY. The bootstrap interview mints the first top-level classes from
+# material that already exists; nothing is pre-allocated, because a class minted
+# ahead of its material is speculative shelving (see protocol/registry-warrant.md).
+#
+# THE TOP LEVEL IS OPEN. Adding a top-level class is an edit to this file plus a
+# Decisions entry — no schema change, no engine change, no allocation table.
+#
+# Value shape (hierarchical): lowercase kebab segments joined by "/". A child is
+# valid only when EVERY segment above it is itself minted here.
+#
+# `warrant` and `decision` are BOTH required on every value: the material that
+# needs the term, and the Decisions entry that signed it off. The decision id is
+# resolved like any other citation, so it must name a real entry.
+#
+#   values:
+#     - value: design-system
+#       gloss: The shared design system and the rules its parts obey.
+#       warrant: 362.1 documents component sizing rules and needs a home.
+#       decision: D-014
+#       minted: "2026-07-07"
+#     - value: design-system/components
+#       gloss: The component library specifically.
+#       warrant: 362.1 states the component rules themselves.
+#       decision: D-014
+#       minted: "2026-07-07"
+#
+# A value that was proposed and REFUSED stays listed, marked suppressed, so the
+# refusal is durable and the term cannot be quietly re-minted:
+#
+#     - value: design-system/motion
+#       warrant: Proposed for 362.4; no material exists, so no warrant was found.
+#       status: suppressed
+#       decision: D-015
+schema-version: 1
+store: knowledge
+registry: domains
+# Load-bearing: this flag is what turns on segment-by-segment membership.
+# Without it a whole path would be judged as one opaque string, so the engine
+# refuses a flat domains registry rather than quietly obeying it.
+hierarchical: true
+values: []

package/payload/templates/knowledge/_registries/form.yaml

@@ -0,0 +1,38 @@
+# The form registry — what KIND of knowledge a leaf is.
+#
+# Ships EMPTY, for the same reason domains does: which forms a project
+# recognizes is a judgement about its own material, not a fact about software.
+# A store whose leaves are all reference material has no warrant for a
+# `runbook` form, and minting one ahead of the first runbook is speculative
+# shelving (see protocol/registry-warrant.md).
+#
+# Flat vocabulary. Value shape: lowercase kebab.
+#
+# The forms the design bench drew from, offered as a starting vocabulary rather
+# than a seeded one — mint the ones your material actually needs:
+#
+#   values:
+#     - value: reference
+#       gloss: States how something is, for lookup.
+#       warrant: 362.1 states the component sizing rules themselves.
+#       decision: D-014
+#       minted: "2026-07-07"
+#     - value: recipe
+#       gloss: The ordered steps for performing a task.
+#       warrant: 100.1 is the step list for adding an export format.
+#       decision: D-014
+#       minted: "2026-07-07"
+#     - value: runbook
+#       gloss: What to do when something is on fire.
+#       warrant: 121.1 is the feed-outage response procedure.
+#       decision: D-014
+#       minted: "2026-07-07"
+#     - value: constraint
+#       gloss: A rule the system must not violate.
+#       warrant: 133.1 states the token rounding rule.
+#       decision: D-014
+#       minted: "2026-07-07"
+schema-version: 1
+store: knowledge
+registry: form
+values: []

package/payload/templates/knowledge/_registries/jurisdictions.yaml

@@ -0,0 +1,20 @@
+# The jurisdictions registry — where a knowledge leaf's claim holds.
+#
+# Ships EMPTY; each value is minted by literary warrant (material must exist to
+# fill it) with a Decisions entry recording the minting. See
+# protocol/registry-warrant.md.
+#
+# Flat vocabulary. Value shape: lowercase kebab. Which granularity a project
+# needs — country, region, market, internal business unit — is the project's own
+# to decide and record; the engine holds no opinion.
+#
+#   values:
+#     - value: us
+#       gloss: United States.
+#       warrant: 362.1 states US-CA-only accessibility rules.
+#       decision: D-014
+#       minted: "2026-07-07"
+schema-version: 1
+store: knowledge
+registry: jurisdictions
+values: []

package/payload/templates/knowledge/_registries/operations.yaml

@@ -0,0 +1,18 @@
+# The operations registry — the verbs a knowledge leaf lets a reader DO.
+#
+# Ships EMPTY; each value is minted by literary warrant (material must exist to
+# fill it) with a Decisions entry recording the minting. See
+# protocol/registry-warrant.md.
+#
+# Flat vocabulary. Value shape: lowercase kebab.
+#
+#   values:
+#     - value: reconcile
+#       gloss: Export a component set to a published package.
+#       warrant: 362.1 documents the export procedure.
+#       decision: D-014
+#       minted: "2026-07-07"
+schema-version: 1
+store: knowledge
+registry: operations
+values: []

package/payload/templates/knowledge/_registries/stage.yaml

@@ -0,0 +1,53 @@
+# The stage registry — where a leaf sits in its promotion lifecycle.
+#
+# THE VOCABULARY IS LOAD-BEARING, BUT THE FILE STILL SHIPS EMPTY. Both facts
+# matter, for the same reasons the anchor registry states.
+#
+# Load-bearing: two engine surfaces read these values through ONE shared
+# predicate (isPrePromotionStatus in engine/lib/load-stores.js). A project that
+# renamed `draft` to `wip` would not be extending a vocabulary — it would be
+# handing the resolver's downrank and preflight's unknown verdict two different
+# answers to "is this leaf provisional yet", which is the exact divergence the
+# shared predicate exists to make impossible. `draft` and `proposed` are the two
+# spellings the predicate recognizes, and they match the concept lifecycle
+# (ontology-concept.schema.json `status`) rather than being a parallel
+# vocabulary. Mint from the four below and no others.
+#
+# Empty anyway: a registry value must cite a Decisions entry that RESOLVES, and
+# a freshly seeded repo's decisions store is empty by design (D-001). The
+# bootstrap interview mints these with an entry of your own.
+#
+# A leaf at `draft` or `proposed` is downranked in resolver output and verdicted
+# `unknown` by preflight. Those are the same leaf, judged once.
+#
+# THREE VALUES, NOT FOUR. There is deliberately no `deprecated` stage yet. The
+# concept lifecycle has one, and it carries real semantics there (§3.5 demotes a
+# deprecated concept's pointer and value findings to warnings) — but no leaf
+# surface implements the matching demotion. A `deprecated` value minted here
+# with nothing behind it would rank a retired leaf ABOVE a draft one and let
+# preflight verdict it `trusted`, which is worse than not offering the term:
+# a vocabulary that looks governed and governs nothing. Retiring a leaf is a
+# later ticket, and it lands with its semantics or not at all.
+#
+# Flat vocabulary. Value shape: lowercase kebab. Mint exactly these:
+#
+#   values:
+#     - value: draft
+#       gloss: Written but not promoted — nothing certifies the claim yet.
+#       warrant: The default stage for every newly authored leaf.
+#       decision: <your entry adopting the lifecycle>
+#       minted: "2026-07-07"
+#     - value: proposed
+#       gloss: Put forward for promotion and awaiting a moderator.
+#       warrant: The second stage the pre-promotion predicate recognizes.
+#       decision: <your entry adopting the lifecycle>
+#       minted: "2026-07-07"
+#     - value: verified
+#       gloss: A moderator promoted it — the citations were checked and hold.
+#       warrant: <the first leaf a moderator promoted>
+#       decision: <your entry adopting the lifecycle>
+#       minted: "2026-07-07"
+schema-version: 1
+store: knowledge
+registry: stage
+values: []

package/payload/templates/knowledge/_rules.yaml

@@ -0,0 +1,6 @@
+# knowledge/_rules.yaml — per-store governance rules (human-only gated writes,
+# citation requirements, accession-id identity). Empty seed: rule items are
+# bootstrap-generated per project. Shape: payload/schemas/rules.schema.json.
+schema-version: 1
+store: knowledge
+rules: []

package/payload/templates/new-kind/README.md

@@ -0,0 +1,107 @@
+# new-kind drafting template (PRD §5.2 DRAFT step)
+
+This directory is the shipped template for drafting a new extractor kind out
+of a `logs/misses/` entry. The pipeline it belongs to — SURVEY → MATCH →
+DRAFT → GATE → INTEGRATE → RE-RUN — is documented in
+`protocol/new-kind-pipeline.md` (client-relative; under `payload/` in the kit
+repo). Read that first; in particular the
+**D-005 hard rule**: validators execute only vendored, versioned,
+test-covered code — a kind drafted in a session is NEVER wired into the
+validator in that same session. Everything drafted from this template enters
+through GATE (PR + tests + review).
+
+The template is deliberately framework-agnostic and demonstrates the shape
+with a trivial demo kind, `line-list` (one `- value` per line; lines split on
+LF or CRLF; blank lines and `#` comments ignored; a value line carrying
+trailing whitespace is *out of the envelope* — it would capture a value that
+can never byte-match its visually identical claim, so the parser hard-errors
+naming the invisible whitespace instead of guessing). The kit's
+extractor-kind framework (KK-07/08) defines how merged kinds register with
+the value validator; a drafted parser conforms to that at INTEGRATE time —
+the contract this template teaches (pure lexical extraction, hard-error on
+out-of-envelope, string values as sets) is the part that never changes.
+
+## What's here
+
+Six files: this README plus the five below. Together they demonstrate the
+pipeline's **three DRAFT artifacts** — the parser, the test fixture, and the
+demo run:
+
+| File | Role |
+|---|---|
+| `parser.example.js` | **DRAFT artifact 1, the parser** — pure function `extractValues(text)` + the demo-run CLI; hard-errors on anything outside its declared syntactic envelope |
+| `fixture/sample.list` | **DRAFT artifact 2, the test fixture (input half)** — a sample anchor (D-009) |
+| `fixture/EXPECTED.yaml` | **DRAFT artifact 2, the test fixture (expected half)** — the value set the parser must extract from `sample.list` |
+| `fixture/demo-anchor.list` | stand-in "live anchor" for **DRAFT artifact 3, the demo run** (the recorded walkthrough below) |
+| `descriptor.example.yaml` | the `enumerates` descriptor fragment the RE-RUN step validates once the kind is merged |
+
+## Drafting a real kind from this template
+
+1. Start from an **open miss**: `logs/misses/<date>-<hex8>.yaml` gives you the
+   anchor `path` and its `shape`. First weigh reification (principle 6) —
+   a registry/enum in the code often beats a bespoke parser.
+2. Copy this directory; rename the kind (lowercase/digits/hyphens); replace
+   the extraction logic in the parser, keeping the four contract points in
+   its header comment (pure/deterministic, hard-error-never-guess, declared
+   envelope, string values).
+3. Rebuild the fixture pair: a `fixture/` sample exercising the envelope
+   (including at least one adversarial-but-extractable shape) and its
+   `EXPECTED.yaml`.
+4. **Demo run** the parser against the live anchor the miss recorded and
+   capture the output for the PR.
+5. Open the GATE PR: parser + fixture + demo-run output. Transition the miss
+   `open → proposed` (`node engine/log-entry.js transition --file
+   logs/misses/<entry>.yaml --to proposed --date YYYY-MM-DD`). Resolution
+   (`proposed → resolved`) happens only after the merged kind's RE-RUN
+   passes; rejection requires a `reason`.
+
+## Recorded walkthrough (manual exercise, 2026-07-08)
+
+Honest seam: this is a documented **manual** exercise of the template, not
+CI. It was run once, by hand, from this directory, and its output is pasted
+verbatim below — byte-honest, not condensed. (Kit CI pins the template
+artifacts against each other and replays these CLI runs, so the transcripts
+can't rot apart from the shipped files.)
+
+**1. Fixture run** — the parser against its own fixture, output matching
+`fixture/EXPECTED.yaml` (exit 0):
+
+```
+$ node parser.example.js fixture/sample.list
+{
+  "kind": "line-list",
+  "file": "fixture/sample.list",
+  "values": [
+    "png",
+    "svg",
+    "pdf"
+  ]
+}
+```
+
+**2. Demo run** — the parser against a throwaway "live anchor"
+(`fixture/demo-anchor.list`, standing in for the miss entry's `path`); this
+output goes on the PR (exit 0):
+
+```
+$ node parser.example.js fixture/demo-anchor.list
+{
+  "kind": "line-list",
+  "file": "fixture/demo-anchor.list",
+  "values": [
+    "grid",
+    "stack"
+  ]
+}
+```
+
+**3. Envelope hard-error** — a file with an out-of-envelope line must fail
+loudly with exit 2, never emit a partial set. `/tmp/bad.list` here contains
+the two lines `- rugby` and `not a value line`:
+
+```
+$ node parser.example.js /tmp/bad.list
+line-list: /tmp/bad.list:2: line is outside the line-list envelope (expected blank, "#" comment, or "- value"): "not a value line"
+```
+
+Exit 2 — a check that never ran is a blocking defect.

package/payload/templates/new-kind/descriptor.example.yaml

@@ -0,0 +1,18 @@
+# new-kind drafting template — the enumerates descriptor the RE-RUN step
+# will validate once the kind has passed GATE and INTEGRATE (PRD §5.2).
+#
+# This is NOT a store file — it is the fragment you paste into the owning
+# concept's `enumerates:` list. Field set per ontology-concept.schema.json
+# ($defs/enumeratesDescriptor): kind + source + values required; symbol and
+# emit only where the kind needs them (this demo kind needs neither).
+#
+# - `kind` names the parser that re-derives the claim (lowercase/digits/
+#   hyphens — the set is open: clients author later kinds through this
+#   template).
+# - `source` must name a listed source-of-truth entry of the concept (§3.5).
+# - `values` is the claim, diffed BOTH WAYS against what the parser extracts
+#   (value-not-in-source / source-value-missing). Strings, byte-exact,
+#   case-sensitive, as sets — quote YAML-1.1 traps like "no"/"on" (§3.5).
+- kind: line-list
+  source: docs/supported-formats.list
+  values: [png, svg, pdf]

package/payload/templates/new-kind/fixture/EXPECTED.yaml

@@ -0,0 +1,6 @@
+# Expected extraction for fixture/sample.list — the other half of the D-009
+# sample-file → expected-values pair. Values are strings compared byte-exact,
+# case-sensitive, as a set (§3.5): order here is presentation only.
+kind: line-list
+file: sample.list
+values: [png, svg, pdf]

package/payload/templates/new-kind/fixture/demo-anchor.list

@@ -0,0 +1,2 @@
+- grid
+- stack

package/payload/templates/new-kind/fixture/sample.list

@@ -0,0 +1,7 @@
+# Extractor fixture for the line-list demo kind (D-009): a sample anchor the
+# parser must read, paired with fixture/EXPECTED.yaml. Blank lines and
+# comments are inside the envelope; any other non-value line hard-errors.
+
+- png
+- svg
+- pdf