unknown-knowledge 2.1.0

package/payload/schemas/ontology-concept.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:ontology-concept",
+  "title": "Ontology concept (PRD §3.1)",
+  "description": "One concept record inside an ontology class file. Truth anchor: the artifact — source-of-truth pointers reference the repo inward. Prose fields (summary, definition) are navigation, never the fact. IDs are minted at PR time within the class's declared range and are immutable once published (§3.5); range membership, duplicate detection, and ref resolution are loader/structural-validator checks (KK-04/KK-05), not record-local. Class files carry the store-file envelope in $defs/storeFile. Schema evolution is additive-only (§3.5, D-013).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "term", "class", "summary", "status"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^K-[0-9]+$",
+      "description": "K-NNN, within the class's declared range; immutable once published."
+    },
+    "term": { "type": "string" },
+    "class": {
+      "type": "string",
+      "description": "Class file this concept belongs to; class files define id ranges. Taxonomy is per-project."
+    },
+    "summary": { "type": "string" },
+    "definition": {
+      "type": "string",
+      "description": "Prose = navigation, never the fact."
+    },
+    "aliases": { "type": "array", "items": { "type": "string" } },
+    "source-of-truth": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "File OR folder paths into the repo. Multi-entry semantics (§3.5): the first entry is the primary owner; additional entries are secondary references only. Every enumerates descriptor's source must name a listed entry. Point at a folder for identity, at a file for facts."
+    },
+    "owned-by": { "type": "string" },
+    "used-by": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/conceptRef" },
+      "description": "Typed refs; must resolve (checked by the structural validator)."
+    },
+    "confusable-with": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/conceptRef" },
+      "description": "Explicit disambiguation; must resolve."
+    },
+    "rationale": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/decisionRef" },
+      "description": "Optional refs into decisions/."
+    },
+    "status": {
+      "enum": ["active", "draft", "deprecated", "proposed"],
+      "description": "§3.5 semantics: draft/proposed = structural checks only; active = all checks blocking-grade; deprecated = pointer/value checks demote to warnings."
+    },
+    "last-verified": { "$ref": "#/$defs/isoDate" },
+    "enumerates": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/enumeratesDescriptor" },
+      "description": "OPTIONAL — presence makes the concept rung-2 (value agreement, diffed both ways)."
+    }
+  },
+  "$defs": {
+    "conceptRef": { "type": "string", "pattern": "^K-[0-9]+$" },
+    "decisionRef": {
+      "type": "string",
+      "pattern": "^D-([0-9]+|[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+)$"
+    },
+    "isoDate": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "enumeratesDescriptor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "source", "values"],
+      "description": "The claim of an enumerable value set plus the extractor recipe to re-derive it. A malformed descriptor is a hard error, never skipped (PRD §4).",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "description": "Extractor kind name (e.g. ts-const-array, swift-enum, dir-modules). Open set: clients author later kinds."
+        },
+        "source": {
+          "type": "string",
+          "description": "Must name a listed source-of-truth entry (§3.5)."
+        },
+        "symbol": {
+          "type": "string",
+          "description": "Declaration symbol inside the source, where the kind needs one."
+        },
+        "emit": {
+          "type": "string",
+          "description": "Which facet the kind emits where both are legitimate (e.g. Swift case names vs raw values, §3.5)."
+        },
+        "pattern": {
+          "type": "string",
+          "description": "dir-modules option: filename filter over the directory listing (e.g. `*.route.ts`). Grammar: `*` matches any run of characters, everything else is literal, the whole name must match. Presence pins the FILE facet — without it the kind emits subdirectory names."
+        },
+        "strip": {
+          "type": "string",
+          "description": "dir-modules option: suffix removed from every emitted name (strip `.route.ts`: home.route.ts → home). A facet name that does not carry the suffix is a hard error, never emitted unstripped."
+        },
+        "values": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Strings only, compared byte-exact and case-sensitive, as sets (§3.5). YAML 1.1 coercion is a real trap (no → false, on → true): quote such values. The loader hard-errors on non-string scalars."
+        }
+      }
+    },
+    "storeFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema-version", "entries"],
+      "description": "Ontology class-file envelope. Every store file carries schema-version (§3.5); evolution is additive-only.",
+      "properties": {
+        "schema-version": { "type": "integer", "minimum": 1 },
+        "entries": { "type": "array", "items": { "$ref": "#" } }
+      }
+    }
+  }
+}

package/payload/schemas/phoenix-event.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:phoenix-event",
+  "title": "Phoenix event mapping (knowledge/_phoenix/<event>.yaml)",
+  "description": "A governed bulk re-taxonomy: the leaf-granular mapping that rewrites a drifted subtree's facets and bumps each touched leaf's edition (UCS-1154). A phoenix event is the ONLY thing that bumps edition in v2. It lands as an ordinary PR — a reviewable diff, not a migration project — carrying this mapping, the leaf rewrites the engine applied from it, the registry mintings the new values needed, and a Decisions entry recording why. The mapping is retained IN the store after the event, because it is what lets the structural validator confirm, from the working tree alone, that every non-1 edition was sanctioned by a phoenix event rather than typed by hand. Identity is never touched: a leaf keeps its accession id across a phoenix event, so nothing that cites it notices, and citations never chase reclassification. The mapping is leaf-granular because class-level rules cannot express a SPLIT — when one class's material divides across two successors, only a per-leaf table can say which leaf went where.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema-version", "event", "decision", "scope", "leaves"],
+  "properties": {
+    "schema-version": { "type": "integer", "minimum": 1 },
+    "event": {
+      "type": "string",
+      "pattern": "^P-[0-9]{3,}$",
+      "description": "The event's id (P-NNN), matching the file's basename so the file a finding names is the event it names."
+    },
+    "title": { "type": "string", "description": "What this event did, in one line — navigation, never the fact." },
+    "decision": {
+      "$ref": "#/$defs/decisionRef",
+      "description": "REQUIRED — the Decisions entry that sanctioned this event (§3.3). A bulk re-taxonomy nobody signed is exactly the ungoverned drift the phoenix mechanism exists to replace, so the mapping cites its warrant like a registry minting does."
+    },
+    "applied": { "$ref": "#/$defs/isoDate", "description": "The day the event was applied, recorded by the steward." },
+    "scope": {
+      "$ref": "#/$defs/scope",
+      "description": "The subtree this event claims. Every leaf inside it must be accounted for by a row below — the completeness gate that makes a phoenix event total rather than partial."
+    },
+    "leaves": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/leafRow" },
+      "description": "The leaf-granular mapping: one row per leaf in scope. Order is the steward's; the engine keys by accession."
+    }
+  },
+  "$defs": {
+    "isoDate": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "decisionRef": { "type": "string", "pattern": "^D-([0-9]+|[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+)$" },
+    "accession": { "type": "string", "pattern": "^L-[0-9]{6}$" },
+    "facetValue": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*(/[a-z0-9]+(-[a-z0-9]+)*)*$" },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["facet", "values"],
+      "properties": {
+        "facet": {
+          "enum": ["facets.domain", "facets.form", "facets.anchor", "facets.stage"],
+          "description": "Which facet this event re-taxonomizes. One facet per event: an event that moved two independent axes at once would be two reviews wearing one diff."
+        },
+        "values": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/facetValue" },
+          "description": "The OLD facet values this event claims. For a hierarchical facet a value claims its whole subtree, so listing a parent claims every descendant — which is what makes 'every leaf in scope' a question the engine can answer without the steward enumerating the tree."
+        }
+      }
+    },
+    "leafRow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/accession",
+          "description": "The leaf this row governs. Identity is the accession and it does not change: this names the SAME leaf before and after, which is why no citation has to move."
+        },
+        "to": {
+          "$ref": "#/$defs/facetValue",
+          "description": "The new value for the scope's facet. Absent means CARRIED FORWARD — the leaf is in scope, was looked at, and deliberately keeps its current value. Carrying forward is not a rewrite, so it bumps no edition; it exists so that 'accounted for' can mean 'considered' rather than only 'moved'."
+        },
+        "why": {
+          "type": "string",
+          "pattern": "\\S",
+          "description": "Why this leaf went where it went. On a split this is the whole substance of the event — the class-level rule cannot say it, so the row must. REQUIRED WHENEVER `to` IS PRESENT: a moved leaf carries the reason it moved. That conditional is enforced by the phoenix command's gate (an `unexplained-move` finding) rather than here, because this document is interpreted by the engine's own validator, whose keyword subset does not include dependentRequired — and a rule stated in a keyword nothing enforces would be contract drift wearing the appearance of a check. Optional in the shape, so a carried-forward row (no `to`) may state a reason or not."
+        }
+      }
+    }
+  }
+}

package/payload/schemas/registry.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:registry",
+  "title": "Governed vocabulary registry (_registries/<name>.yaml)",
+  "description": "A store-level registry: the closed vocabulary one facet draws its values from (PRD §3, UCS-1148). Registries are governed files, not schema enums — a value is MINTED into a registry by literary warrant (material exists that needs it) and every minting is a Decisions entry, so the vocabulary grows by steward review rather than by an engine release. Hierarchical registries (domain) mint each path segment as its own value and a child path is valid only when every segment above it is minted; the TOP level is open by construction — a new top-level class is a registry edit plus a Decisions entry, never a schema or engine change. A rejected value is SUPPRESSED rather than deleted (status: suppressed), so a vocabulary proposal that was considered and refused stays visible and cannot be silently re-minted. Membership of facet values in their registry is a structural-validator check (KK-05); this schema governs the registry file itself. Schema evolution is additive-only (§3.5, D-013).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema-version", "store", "registry", "values"],
+  "properties": {
+    "schema-version": { "type": "integer", "minimum": 1 },
+    "store": { "enum": ["ontology", "knowledge", "decisions"] },
+    "registry": {
+      "type": "string",
+      "description": "The registry's name — must equal the file's basename, so the file a finding names is the registry it names (a structural-validator check)."
+    },
+    "hierarchical": {
+      "type": "boolean",
+      "description": "When true, values are path segments joined by '/' and a child path is valid only if every segment above it is itself minted. Absent means flat."
+    },
+    "values": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/registryValue" },
+      "description": "The minted vocabulary. Order is the steward's; the engine compares as a set."
+    }
+  },
+  "$defs": {
+    "isoDate": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "decisionRef": { "type": "string", "pattern": "^D-([0-9]+|[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+)$" },
+    "registryValue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["value", "warrant", "decision"],
+      "properties": {
+        "value": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*(/[a-z0-9]+(-[a-z0-9]+)*)*$",
+          "description": "The minted term: lowercase kebab segments, '/'-joined for a hierarchical registry."
+        },
+        "gloss": { "type": "string", "description": "What the term means here — prose is navigation, never the fact." },
+        "warrant": {
+          "type": "string",
+          "pattern": "\\S",
+          "description": "The literary warrant: the material that exists and needs this value. A value minted without material to fill it is speculative shelving, which is what this field refuses — so it must carry actual text, not whitespace."
+        },
+        "status": {
+          "enum": ["minted", "suppressed"],
+          "description": "Absent means minted. A suppressed value was proposed and REJECTED — it stays listed so the refusal is durable and the term cannot be quietly re-minted; using it is a membership finding like any unminted value."
+        },
+        "decision": {
+          "$ref": "#/$defs/decisionRef",
+          "description": "REQUIRED — the Decisions entry recording this minting or suppression (§3.3). Every registry edit is a governed act with a written rationale, so a value that cites no decision is a vocabulary change nobody signed. The citation is resolved like any other cross-store ref: an id naming no decision is an unresolved-ref error."
+        },
+        "minted": { "$ref": "#/$defs/isoDate" }
+      }
+    }
+  }
+}

package/payload/schemas/rules.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:rules",
+  "title": "Store rules (_rules.yaml)",
+  "description": "Second hop of the navigational grammar (PRD §3): per-store governance rules — id ranges per class, write gates, staleness policy. The rule item shape is bootstrap-generated per project and formalized additively by the taxonomy issues; v1 pins only the envelope so seeded files carry schema-version from day one (§3.5, seeded-once means conventions cannot be retrofitted).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema-version", "store", "rules"],
+  "properties": {
+    "schema-version": { "type": "integer", "minimum": 1 },
+    "store": { "enum": ["ontology", "knowledge", "decisions"] },
+    "rules": { "type": "array" }
+  }
+}

package/payload/schemas/survey-scope.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:survey-scope",
+  "title": "Survey scope (PRD §4/§6)",
+  "description": "survey-scope.yaml — the human-confirmed include/exclude traversal boundary from the bootstrap scope+taxonomy gate, persisted at the client repo root. The honor-it contract: once this file exists, survey-map bounds its map to it, and audit/reflect sweeps never rescan excluded areas (widening happens via retrieval-miss findings, never re-litigation). Paths are repo-root-relative directory or file prefixes; exclude wins over include. Evolution is additive-only (§3.5, D-013).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema-version", "include"],
+  "properties": {
+    "schema-version": { "type": "integer", "minimum": 1 },
+    "include": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "Root-relative path prefixes that ARE product surface. Trailing slashes are normalized away (src/ means src). The special prefix '.' covers root-level files only (package.json etc.), never subdirectories. An empty include would silently survey nothing — hence minItems 1; likewise an include matching zero tracked files is an engine failure, never a silent empty survey."
+    },
+    "exclude": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Root-relative path prefixes carved OUT of the includes (vendored/generated/infra). Exclude wins over include."
+    }
+  }
+}

package/payload/templates/decisions/_catalog.yaml

@@ -0,0 +1,7 @@
+# decisions/_catalog.yaml — navigational entry point for the decisions store
+# (catalog -> entries/D-NNN files; decisions has no _rules.yaml, PRD §9.1).
+# Empty seed: entries are appended through the gated decisions write path (§3.5).
+# Shape: payload/schemas/catalog.schema.json. schema-version evolves additively.
+schema-version: 1
+store: decisions
+entries: []

package/payload/templates/decisions/_registries/graduation-categories.yaml

@@ -0,0 +1,42 @@
+# Trust graduation category table (UCS-1155) — which change categories may ever
+# graduate from full inspection to sampling, and which are permanently gated.
+#
+# Seeded EMPTY, like every other registry, and for the same reason plus one of
+# its own. The shared reason: every row must cite a Decisions entry that
+# resolves, and a seeded repo's decisions store is empty by design (D-001), so
+# shipped rows would hand every client a broken ref.
+#
+# The reason particular to this table: a graduation-eligible row is a standing
+# claim that a class of change is mechanical ENOUGH IN THIS PROJECT to be
+# sampled rather than read. The kit cannot know that. Whether "alias additions"
+# are mechanical depends on what this project's aliases do — in a store where an
+# alias steers retrieval into regulated material, they are not mechanical at
+# all. Shipping that judgment pre-made would be the kit deciding how much
+# someone else's work gets read.
+#
+# So the vocabulary is yours to mint, and the shapes below are the guidance:
+#
+#   ELIGIBLE — mechanical categories. The change is checkable by looking at it,
+#   and being right about it N times running is real evidence about the N+1th.
+#   The candidates named in the design: alias additions, verified bumps, paths
+#   edges, see-also links.
+#
+#   GATED — judgment categories, permanently. New domain classes, contradicts
+#   and supersedes edges, authority assignments, and ANYTHING CITATION-BEARING.
+#   These stay gated however long the clean streak, because the streak is
+#   evidence about a different question than the one they ask: a correct
+#   authority assignment ten times over says the assigner has been careful, not
+#   that the eleventh source's trustworthiness can go unread.
+#
+# Every row needs a `warrant` — for a gated row, name the judgment the change
+# requires that no streak removes. An `eligible` row needs a `threshold` (N
+# consecutive approved-unmodified cycles); a `gated` row must not carry one.
+#
+# v1 DOES NOT COMPUTE THE COUNTS. The threshold is the bar a moderator judges
+# the recorded approved-unmodified counts against by hand; the analytics are
+# manual (docs/steward-guide.md). Citation spot-checks stay in the sampling plan
+# at every trust level, including the most graduated.
+schema-version: 1
+store: decisions
+table: graduation-categories
+categories: []

package/payload/templates/decisions/phoenix-event.yaml

@@ -0,0 +1,74 @@
+# Decisions-entry template — a phoenix event (UCS-1154).
+#
+# A phoenix event is a governed bulk re-taxonomy: a drifted subtree's facets are
+# rewritten from a leaf-granular mapping, every leaf the event moves has its
+# `edition` bumped — the only thing that ever bumps it — and the whole thing
+# lands as an ordinary PR. Copy this file to decisions/entries/<id>-<slug>.yaml,
+# fill it, and open ONE PR carrying:
+#
+#   - this entry,
+#   - the mapping, at knowledge/_phoenix/<event>.yaml,
+#   - the registry mintings the new values need (each with its own warrant),
+#   - the leaf rewrites, produced by the engine and never by hand:
+#         node payload/engine/phoenix.js <event> --root <dir>            # dry run
+#         node payload/engine/phoenix.js <event> --root <dir> --apply    # write
+#
+# The mapping file STAYS in the store after the event. It is what lets the
+# structural validator confirm that every edition above 1 was sanctioned by an
+# event, reading only the working tree — a governance rule checkable solely by
+# reading git history is a rule that is not checked.
+#
+# The two rules this entry exists to evidence:
+#
+#   THE MAPPING IS LEAF-GRANULAR. A class-level rename cannot express a SPLIT —
+#   when one class's material divides across two successors, only a per-leaf
+#   table can say which leaf went where, and the `why` on each row is the
+#   substance a reviewer reads.
+#
+#   IDENTITY DOES NOT MOVE. Accession ids are untouched, so every citation into
+#   these leaves stays valid across the event. If a proposal requires renaming
+#   or reissuing an id, it is not a phoenix event.
+#
+# 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 a bulk rewrite would end up
+# carrying a rationale nobody wrote. Every other field is real: fill those two
+# and the entry validates.
+schema-version: 1
+entries:
+  - id: D-YYYY-MM-DD-phoenix-example-split
+    title: "Phoenix: <what splits, merges or moves> (edition <n>)"
+    # `governance` — an event changes how the Store is filed, not how the engine
+    # works.
+    category: governance
+    status: proposed
+    date: "YYYY-MM-DD"
+    deciders: [<steward>]
+    # THE DRIFT. Name the material whose classification stopped matching it, and
+    # say how you noticed. "The tree would be tidier" is the case this refuses:
+    # a re-taxonomy costs every reader their memory of where things live, so the
+    # warrant is that the CURRENT shape actively misfiles material — two kinds of
+    # thing under one class that no longer share a reader, a class nobody looks
+    # in, a name that stopped meaning what it says.
+    context: >-
+      <Which leaves are filed where, and why that filing no longer serves the
+      people reading them.>
+    # What moves where, and — if this is a split — why no class-level rule could
+    # express it. Name the event id whose mapping carries the per-leaf rows.
+    decision: >-
+      <Split/merge/move <old> into <new>. Apply as phoenix event P-NNN, whose
+      mapping (knowledge/_phoenix/P-NNN.yaml) records where each leaf went and
+      why.>
+    # Say the edition bump out loud, and say what did NOT change: an event that
+    # quietly moved identity would break every citation into the subtree, and
+    # stating the invariant here is how a reviewer knows to check it.
+    consequences: >-
+      <Each moved leaf's edition goes <n-1> -> <n>. No accession id changes, so
+      every citation into these leaves stays valid and nothing that cites them
+      needs editing. Leaves carried forward keep their edition — they were
+      considered and deliberately left alone.>
+    supersedes: []
+    # The leaves this event touched. The same accessions are valid before AND
+    # after — that is the property being demonstrated, not a coincidence.
+    relates-to:
+      leaves: []

package/payload/templates/decisions/reflect-mint-proposal.yaml

@@ -0,0 +1,100 @@
+# Decisions-entry template — a reflect MINT PROPOSAL (UCS-1160).
+#
+# Reflect is where misses become tomorrow's deterministic edges. A corroborated
+# cluster of residue or document-candidate findings is evidence that the store
+# has no word for something the material keeps naming. Minting that word — a
+# term, an alias, an operation, or a domain class — is a governed act, and this
+# file is the shape of the rationale that sanctions it.
+#
+# Copy this file to decisions/entries/<id>-<slug>.yaml, fill it, and open ONE
+# PR carrying the entry, the registry (or concept) edit that cites it, and the
+# findings that supplied the warrant. Conduct in full:
+# protocol/skills/knowledge-reflect.md (Minting conduct) and
+# protocol/registry-warrant.md.
+#
+# Draft with a provisional date-suffixed id (D-YYYY-MM-DD-slug) and
+# `status: proposed`; the steward assigns the final D-NNN at acceptance (§3.5).
+# Agents draft; humans approve.
+#
+# The two rules this entry exists to evidence:
+#   ONE FINDING IS A DATA POINT, THREE ARE A PATTERN. `context` must name at
+#   least three DISTINCT fragments before a mint reaches the gate. "Distinct"
+#   is defined once, in protocol/skills/knowledge-reflect.md under Minting
+#   conduct ("What three distinct fragments means") — read it there rather
+#   than inferring it here. The short of it: it counts independent resolution
+#   events, not files, so three logs from ONE session are one data point.
+#   A VALUE IS MINTED ONLY ON LITERARY WARRANT. If `context` cannot name
+#   material that exists NOW, the value is not ready — corroboration says the
+#   word keeps coming up, warrant says there is something for it to hold.
+#
+# WHAT THE VALIDATOR CATCHES, AND WHAT ONLY A READER CATCHES.
+#
+# MACHINE-REFUSED — the `id` and `date` placeholders below are DELIBERATELY not
+# valid (`YYYY` is not four digits), so pasting this file unedited fails
+# validation and never produces a Decisions entry. (Same conduct as
+# registry-minting.yaml and the audit's `K-XXX` drafts.)
+#
+# GREEN BUT STILL A PLACEHOLDER — filling those two makes the file VALIDATE,
+# and these five fields still hold <angle-bracket> text that no validator
+# judges, because they are free prose the schema deliberately leaves open:
+#
+#   title         "Mint <value> in the <registry> registry ..."
+#   deciders      ["<steward>"]
+#   context       "<Which material exists, and why no minted value fits it ...>"
+#   decision      "Mint <value> in <registry>. ..."
+#   consequences  "<What this obliges ...>"
+#
+# A green validation on this file means "the shape is right", NEVER "the
+# rationale is written". Those five are caught by the human at the gate or not
+# at all — which is the honest state of affairs, not an oversight: patterning
+# them would constrain every real Decisions entry in the store, and a validator
+# cannot tell a written warrant from a plausible-looking sentence anyway.
+# Replace every <angle-bracket> before this entry goes to the gate.
+schema-version: 1
+entries:
+  - id: D-YYYY-MM-DD-mint-example-from-reflect
+    title: Mint <value> in the <registry> registry (reflect cycle <date>)
+    # `governance` — minting a vocabulary value changes what the Store may say,
+    # not how the engine works.
+    category: governance
+    status: proposed
+    date: "YYYY-MM-DD"
+    deciders: [<steward>]
+    # THE WARRANT, plus the CORROBORATION that raised it. Name the material that
+    # exists and needs this value, AND the findings that kept landing on it.
+    # Reflect's own recommendation list is not evidence — the fragments are.
+    # "We will need it later" is the case the warrant rule refuses; "it came up
+    # once" — and "it came up three times in one sitting" — are the cases the
+    # corroboration rule refuses.
+    context: >-
+      <Which material exists, and why no minted value fits it. Then: which
+      DISTINCT fragments corroborate it (name the paths), over which sessions
+      and dates — distinctness counts independent resolution events, not files
+      — and what resolved alongside the unresolved term (the findings'
+      `resolved-context`), which is what localizes the gap. For a document
+      candidate, name the section the
+      findings' `section` locators point at and say what reading it confirmed:
+      a candidate is a claim about the map until someone opens the source.>
+    # What is being minted, at which level, and in which vocabulary. For a
+    # hierarchical domain path, mint every segment: a child may not hang off an
+    # unminted parent.
+    decision: >-
+      Mint <value> in <registry>. <For an alias: name the concept it attaches to
+      and the surface form the findings kept using. For an operation: name the
+      verb and what it operates on. For a new top-level domain class: this is a
+      registry edit plus this entry — the top level is open, so no schema or
+      engine change is involved.>
+    # For a SUPPRESSION, keep the same shape and say what was refused and why.
+    # The value stays listed with `status: suppressed` rather than being
+    # deleted, so the refusal is durable and the term cannot be quietly
+    # re-minted — and the next reflect cycle that clusters the same residue sees
+    # that this term was already considered.
+    consequences: >-
+      <What this obliges: leaves to reclassify, siblings this now sits beside,
+      the residue this stops producing, or — on a suppression — where the
+      material should go instead.>
+    supersedes: []
+    # A re-minting REVERSES an earlier suppression: name that decision here and
+    # say in `context` why the refusal no longer holds.
+    relates-to:
+      leaves: []

package/payload/templates/decisions/registry-minting.yaml

@@ -0,0 +1,58 @@
+# Decisions-entry template — minting or suppressing a registry value (UCS-1148).
+#
+# Every registry edit is a governed act with a written rationale. Copy this file
+# to decisions/entries/<id>-<slug>.yaml, fill it, and open ONE PR carrying the
+# entry, the registry edit that cites it, and the material that supplied the
+# warrant. Conduct in full: protocol/registry-warrant.md.
+#
+# Draft with a provisional date-suffixed id (D-YYYY-MM-DD-slug) and
+# `status: proposed`; the steward assigns the final D-NNN at acceptance (§3.5).
+# Agents draft; humans approve.
+#
+# The one rule this entry exists to evidence:
+#   A VALUE IS MINTED ONLY WHEN MATERIAL EXISTS TO FILL IT (literary warrant).
+#   If `context` cannot name material that exists NOW, the value is not ready.
+#
+# 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 a registry value would end
+# up carrying a warrant nobody wrote. (Same conduct as the audit's `K-XXX`
+# drafts.) Every other field is real: fill those two and the entry validates.
+schema-version: 1
+entries:
+  - id: D-YYYY-MM-DD-mint-example-domain
+    title: Mint <value> in the <registry> registry
+    # `governance` — a registry edit changes what the Store may say, not how the
+    # engine works.
+    category: governance
+    status: proposed
+    date: "YYYY-MM-DD"
+    deciders: [<steward>]
+    # THE WARRANT. Name the material that exists and needs this value: the
+    # leaves, documents, or body of work with nowhere to sit. "We will need it
+    # later" is the case the rule refuses — speculative shelving invites authors
+    # to file knowledge under a heading nobody chose deliberately.
+    context: >-
+      <Which material exists, and why no minted value fits it. For a
+      hierarchical domain, say why it belongs at this level rather than under an
+      existing class.>
+    # What is being minted, at which level, and in which registry. For a
+    # hierarchical path, mint every segment: a child may not hang off an
+    # unminted parent.
+    decision: >-
+      Mint <value> in <registry>. <For a new top-level domain class: this is a
+      registry edit plus this entry — the top level is open, so no schema or
+      engine change is involved.>
+    # For a SUPPRESSION, keep the same shape and say what was refused and why.
+    # The value stays listed with `status: suppressed` rather than being
+    # deleted, so the refusal is durable and the term cannot be quietly
+    # re-minted. Deleting it would lose the decision and invite the same
+    # proposal again with no memory of how it went.
+    consequences: >-
+      <What this obliges: leaves to reclassify, siblings this now sits beside,
+      or — on a suppression — where the material should go instead.>
+    supersedes: []
+    # A re-minting REVERSES an earlier suppression: name that decision here and
+    # say in `context` why the refusal no longer holds.
+    relates-to:
+      leaves: []