unknown-knowledge 2.1.0

package/payload/schemas/decision-entry.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:decision-entry",
+  "title": "Decision entry (PRD §3.3)",
+  "description": "One ADR-style record in decisions/entries/. Truth anchor: the team. Append-mostly: status transitions never rewrite context/decision/consequences. Drafted with provisional date-suffixed ids (D-YYYY-MM-DD-slug); the steward assigns the final D-NNN at acceptance (§3.5). Chain resolution and acyclicity are structural-validator checks (KK-05). Schema evolution is additive-only (§3.5, D-013).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "title", "category", "status", "date", "deciders", "context", "decision"],
+  "properties": {
+    "id": {
+      "$ref": "#/$defs/decisionRef",
+      "description": "Final D-NNN (immutable once published) or provisional date-suffixed draft id (§3.5)."
+    },
+    "title": { "type": "string" },
+    "category": {
+      "enum": ["architecture", "governance", "scope", "process", "trust"]
+    },
+    "status": {
+      "enum": ["proposed", "accepted", "addressed", "archived", "rejected", "superseded"],
+      "description": "Lifecycle: proposed → accepted → addressed → archived (+ rejected, superseded)."
+    },
+    "date": { "$ref": "#/$defs/isoDate" },
+    "deciders": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+    "context": {
+      "type": "string",
+      "description": "Append-mostly: transitions never rewrite recorded reasoning."
+    },
+    "decision": { "type": "string" },
+    "consequences": { "type": "string" },
+    "supersedes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/decisionRef" },
+      "description": "Chains must resolve and be acyclic (structural validator)."
+    },
+    "superseded-by": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/decisionRef" }
+    },
+    "relates-to": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Sideways typed refs to concepts and leaves; never embedded content across store lines (PRD §3).",
+      "properties": {
+        "concepts": { "type": "array", "items": { "$ref": "#/$defs/conceptRef" } },
+        "leaves": { "type": "array", "items": { "$ref": "#/$defs/leafRef" } },
+        "decisions": { "type": "array", "items": { "$ref": "#/$defs/decisionRef" } }
+      }
+    },
+    "graduation": {
+      "$ref": "#/$defs/graduation",
+      "description": "OPTIONAL typed block marking this entry as a trust graduation or revocation (UCS-1155). Present only on the entries that move the trust boundary; an ordinary decision omits it. Deliberately a BLOCK on the existing record rather than a forked record kind: a graduation IS an ADR — it has context, a decision, consequences, deciders and a date, and it supersedes and is superseded like any other — so forking the kind would duplicate the whole envelope to add three fields, and split the decisions store into two things a steward has to know apart. The validator holds this block against the graduation category table (graduation-categories.schema.json)."
+    },
+    "provenance": {
+      "$ref": "#/$defs/provenance",
+      "description": "Who authored this entry and with which skill revision (UCS-1149's leaf provenance, applied to decision entries by UCS-1155). Optional, so the installed base and every fixture written before it stay valid. It is what makes a defect traceable: when a graduated category produces a bad change, the question is not only which entry was wrong but which AUTHOR and which SKILL VERSION produced it — a bad skill revision is then traceable like any other defect, and every entry it touched is findable rather than guessed at."
+    }
+  },
+  "$defs": {
+    "graduation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action", "category"],
+      "description": "A move of the trust boundary: this entry either GRADUATES a change category from full inspection to sampling, or REVOKES a graduation and returns the category to full inspection (UCS-1155). Both directions are the same shape because both are the same governed act — a recorded, reviewable, reversible statement about how much reading a class of change gets — and giving revocation a lesser shape would make un-earning trust cheaper to record than earning it, which is backwards.",
+      "properties": {
+        "action": {
+          "enum": ["graduate", "revoke"],
+          "description": "`graduate` — the category moves from full inspection to sampling. `revoke` — a graduation is withdrawn and the category returns to full inspection. Revocation is AUTOMATIC on any defect found in a graduated category (conduct, documented in the steward guide): the steward records it, the mechanism does not wait for a judgment call about whether this particular defect was bad enough."
+        },
+        "category": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+          "description": "The change category being graduated or revoked — must name a row in the graduation category table (decisions/_registries/). An entry naming an absent category is a validator finding, as is a graduation for a permanently gated one: autonomy that cites no declared category is autonomy nobody scoped."
+        },
+        "observed-cycles": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The count of consecutive approved-unmodified cycles the moderator OBSERVED for this category, as recorded by reflect. v1 DOES NOT COMPUTE OR VERIFY THIS NUMBER — the analytics stay manual, and this field is the steward's written record of what they judged against the table's threshold, not an engine-derived total. Recording it is what makes the judgment reviewable after the fact: a reader can ask whether the number was met, even though no code asserts the number itself. REQUIRED on a `graduate` (a `graduation-field-shape` finding otherwise) — a grant with no written count is exactly the unreviewable judgment the manual-analytics stance depends on not existing. Meaningless but tolerated on a `revoke`, which is triggered by a defect rather than by a count. The action-conditional rules are enforced by the structural validator rather than here, because this document is interpreted by the engine's own validator, whose keyword subset has no conditional."
+        },
+        "revokes": {
+          "$ref": "#/$defs/decisionRef",
+          "description": "On a `revoke`, the graduation entry being withdrawn. When present it is resolved like any other cross-store ref, so an id naming no decision is an unresolved-ref error — and the structural validator additionally checks WHAT it names: the target must carry a graduation block, with action `graduate`, for this entry's own category, since resolution alone cannot tell a grant from an unrelated ADR (`disconnected-revocation`). REFUSED on a `graduate`, which grants rather than withdraws (`graduation-field-shape`). REQUIRED WHENEVER A GRADUATION FOR THE SAME CATEGORY EXISTS in the store — otherwise the store asserts both a graduation and its revocation with nothing linking them, and a reader cannot tell whether the graduation still stands (a `disconnected-revocation` finding). It stays OPTIONAL when no graduation for the category exists, which is the standing-position case: recording that a never-graduated category remains at full inspection is legitimate and has nothing to point at. That conditional is enforced by the structural validator rather than here, because this document is interpreted by the engine's own validator, whose keyword subset has no conditional — and a rule stated in a keyword nothing enforces is contract drift wearing the appearance of a check."
+        },
+        "defect": {
+          "type": "string",
+          "description": "On a `revoke`, what went wrong — the defect that triggered it. Prose, because the point is that a human can read why trust was withdrawn; the machine-checkable half is that a revocation exists and names something. REQUIRED on a `revoke` and REFUSED on a `graduate` (a `graduation-field-shape` finding either way): revocation is automatic ON A DEFECT, so a revocation naming none records that trust was withdrawn for no stated reason and leaves the next graduation of that category with nothing to have fixed — while a defect on a GRANT is withdrawal vocabulary on an entry moving the other direction. Validator-enforced, per the note on `observed-cycles`."
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Who wrote this entry and with which authoring skill (UCS-1149's leaf shape, applied to decision entries by UCS-1155). Recorded, never judged: no registry governs it, because an author name and a skill version are facts about how the entry came to exist rather than governed vocabulary. Surfaced in validator and resolver output so a defect is traceable to both.",
+      "properties": {
+        "author": {
+          "type": "string",
+          "description": "Who authored the entry — a human steward or the agent that drafted it."
+        },
+        "skill-version": {
+          "type": "string",
+          "description": "The version of the authoring skill that produced the entry, so a systematic drafting defect can be traced to the vintage that introduced it — the property that makes a bad skill revision recallable rather than merely regrettable."
+        }
+      }
+    },
+    "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-]+)$"
+    },
+    "leafRef": { "type": "string", "pattern": "^L-[0-9]{6}$" },
+    "isoDate": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "storeFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema-version", "entries"],
+      "description": "Decision entries-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/finding.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:finding",
+  "title": "Finding log fragment (PRD §3.4)",
+  "description": "One agent-appended finding in logs/findings/ — ONE FILE PER ENTRY (D-010), so concurrent sessions never merge-conflict; the fragment is the store file and carries schema-version (§3.5). Raw signal, no judgment at capture time. Capture content policy: concept IDs and file paths only — never verbatim user text or secrets; committed fragments are permanent git history. Lifecycle open → proposed → resolved/rejected; recurrences re-open the same entry (never duplicate), appending to occurrences. The reflect skill (KK-22) consolidates fragments and prunes resolved ones; uncorroborated entries age out to archived with a rollup note. Sibling logs live in logs/misses/ (miss.schema.json) and logs/gaps/ (gap.schema.json). Schema evolution is additive-only (§3.5, D-013).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema-version", "date", "trigger", "summary", "status"],
+  "properties": {
+    "schema-version": { "type": "integer", "minimum": 1 },
+    "date": { "$ref": "#/$defs/isoDate" },
+    "trigger": {
+      "enum": ["correction", "recurrence", "retrieval-struggle", "retrieval-miss", "quarantine"],
+      "description": "The five capture triggers; quarantine is engine-attributed."
+    },
+    "session": {
+      "type": "string",
+      "description": "Platform/session hint."
+    },
+    "summary": {
+      "type": "string",
+      "description": "Concept IDs and file paths only — never verbatim user text or secrets."
+    },
+    "consulted": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "concepts": { "type": "array", "items": { "$ref": "#/$defs/conceptRef" } },
+        "leaves": { "type": "array", "items": { "$ref": "#/$defs/leafRef" } }
+      }
+    },
+    "residue": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "The unresolved terms this finding is about (UCS-1160) — resolve's `decomposition.residue` for a query, or a ranked candidate's term for a document. Terms are the store's own tokens, never quoted user prose (capture content policy)."
+    },
+    "resolved-context": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "What DID resolve in the same ask (UCS-1160) — resolve's `decomposition.resolved-context`: the operations, concept ids, and jurisdictions the query landed in. A bare unresolved token is a finding nobody can act on; the context localizes the gap precisely enough that the minting decision writes itself."
+    },
+    "section": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Where a DOCUMENT candidate was found (UCS-1160) — the section locator from the --doc coverage map, so reflect can open the section just-in-time rather than re-reading the document. Absent on query residue, which has no document to address. EXACTLY ONE of line/page is required: coverage emits {line, endLine} for line-addressed sources and {page, object} for pdf, never both. Neither is an underspecified locator (the coordinate-free claim the locator exists to replace); both is contradictory. That rule is enforced by the VALIDATOR as the `locator-shape` convention, not by this document, because the engine's JSON Schema subset has no conditional keywords (no oneOf/anyOf/allOf/not) — writing one here would promise a rule nothing checks.",
+      "required": ["document", "address"],
+      "properties": {
+        "document": { "type": "string", "description": "Repo-relative path of the document the candidate fell out of." },
+        "address": { "type": "string", "description": "The section's heading text — the coverage map's own address for it." },
+        "line": { "type": "integer", "minimum": 1, "description": "First line of the section's range; absent for page-addressed sources (pdf). Exactly one of line/page — see the `locator-shape` convention above." },
+        "page": { "type": "integer", "minimum": 1, "description": "Page number for page-addressed sources (pdf); absent for line-addressed ones. Exactly one of line/page — see the `locator-shape` convention above." }
+      }
+    },
+    "status": {
+      "enum": ["open", "proposed", "resolved", "rejected"],
+      "description": "Lifecycle: open → proposed → resolved/rejected; re-open-not-duplicate."
+    },
+    "verified": {
+      "$ref": "#/$defs/isoDate",
+      "description": "Stamped by the transition helper when the entry resolves (validator re-run passed); removed on re-open."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Required on rejection — rejections record the reason (§8)."
+    },
+    "occurrences": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/isoDate" },
+      "description": "Re-open dates: recurrences re-open the same entry, never duplicate (§8)."
+    }
+  },
+  "$defs": {
+    "conceptRef": { "type": "string", "pattern": "^K-[0-9]+$" },
+    "leafRef": { "type": "string", "pattern": "^L-[0-9]{6}$" },
+    "isoDate": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }
+  }
+}

package/payload/schemas/gap.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:gap",
+  "title": "Gap-log fragment (PRD §3.4)",
+  "description": "One request no protocol/skill could route, recorded in logs/gaps/ — ONE FILE PER ENTRY (D-010), so concurrent sessions never merge-conflict; the fragment is the store file and carries schema-version (§3.5). Capture content policy: concept IDs and file paths only — never verbatim user text or secrets; committed fragments are permanent git history. Lifecycle open → proposed → resolved/rejected; recurrences re-open the same entry (never duplicate), appending to occurrences. The reflect skill (KK-22) consolidates fragments and prunes resolved ones; uncorroborated entries age out to archived with a rollup note. Schema evolution is additive-only (§3.5, D-013).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema-version", "date", "summary", "status"],
+  "properties": {
+    "schema-version": { "type": "integer", "minimum": 1 },
+    "date": { "$ref": "#/$defs/isoDate" },
+    "summary": {
+      "type": "string",
+      "description": "What could not be routed, by concept IDs and file paths only — never verbatim user text or secrets."
+    },
+    "session": {
+      "type": "string",
+      "description": "Opaque platform/session hint — an ID, never quoted session content."
+    },
+    "consulted": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Nearest concepts/leaves consulted before declaring the gap.",
+      "properties": {
+        "concepts": { "type": "array", "items": { "$ref": "#/$defs/conceptRef" } },
+        "leaves": { "type": "array", "items": { "$ref": "#/$defs/leafRef" } }
+      }
+    },
+    "status": {
+      "enum": ["open", "proposed", "resolved", "rejected"],
+      "description": "Lifecycle: open → proposed → resolved/rejected; re-open-not-duplicate."
+    },
+    "verified": {
+      "$ref": "#/$defs/isoDate",
+      "description": "Stamped by the transition helper when the entry resolves (validator re-run passed); removed on re-open."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Required on rejection — rejections record the reason (§8)."
+    },
+    "occurrences": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/isoDate" },
+      "description": "Re-open dates: recurrences re-open the same entry, never duplicate (§8)."
+    }
+  },
+  "$defs": {
+    "conceptRef": { "type": "string", "pattern": "^K-[0-9]+$" },
+    "leafRef": { "type": "string", "pattern": "^L-[0-9]{6}$" },
+    "isoDate": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }
+  }
+}

package/payload/schemas/graduation-categories.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:graduation-categories",
+  "title": "Trust graduation category table (decisions/_registries/graduation-categories.yaml)",
+  "description": "The governed table declaring which CHANGE CATEGORIES may ever graduate from full inspection to sampling, and which are permanently gated (PRD §2 'autonomy earned per category', UCS-1155). Autonomy is per category and never per leaf: a category is the unit because a mechanical change class (alias additions, verified bumps, paths edges, see-also links) can accumulate evidence about ITSELF, while an individual record cannot — one leaf approved ten times says nothing about the eleventh leaf. Two eligibilities, and the split is the whole mechanism: `eligible` categories name an integer threshold N of approved-unmodified cycles after which a steward MAY graduate them, and `gated` categories (new domain classes, contradicts/supersedes edges, authority assignments, anything citation-bearing) can never graduate at all — a judgment call does not become mechanical by being made correctly N times. Graduating an eligible category and revoking any graduation are both Decisions entries carrying the typed `graduation:` block (decision-entry.schema.json); the validator holds those entries against this table, so an entry naming a category absent here, or graduating a gated one, is a finding rather than a silent pass. v1 DOES NOT COMPUTE the approved-unmodified counts: the threshold is what the moderator judges the recorded counts against by hand, and the analytics stay manual (steward-guide.md). This schema governs the table file itself. Schema evolution is additive-only (§3.5, D-013).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema-version", "store", "table", "categories"],
+  "properties": {
+    "schema-version": { "type": "integer", "minimum": 1 },
+    "store": {
+      "enum": ["decisions"],
+      "description": "Always `decisions`. The table governs the change PROCESS — who may write without full inspection — which is the team's truth anchor (D-003), not the artifact's or the world's. A graduation table filed under knowledge/ would be claiming the world decides how this repo is reviewed."
+    },
+    "table": {
+      "type": "string",
+      "description": "The table's name — must equal the file's basename, so the file a finding names is the table it names (a loader check, mirroring registries)."
+    },
+    "categories": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/category" },
+      "description": "The declared change categories. 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-]+)$" },
+    "category": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["category", "eligibility", "warrant", "decision"],
+      "properties": {
+        "category": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+          "description": "The change category's name: lowercase kebab, e.g. `alias-additions`. Names a CLASS OF EDIT, never a record — 'alias additions' is a category, 'L-000117' is not."
+        },
+        "eligibility": {
+          "enum": ["eligible", "gated"],
+          "description": "`eligible` — this category MAY graduate once its threshold of approved-unmodified cycles is met and a steward records the graduation. `gated` — permanently gated: it may never graduate, whatever the evidence. The distinction is mechanical-versus-judgment, not easy-versus-hard: an alias addition is checkable by looking at it, while an authority assignment encodes how far a source can be trusted, and being right about that N times running is not evidence that the N+1th needs no reading."
+        },
+        "threshold": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "N — the consecutive approved-unmodified cycles this category must accumulate before a steward may graduate it. REQUIRED for an `eligible` category and REFUSED for a `gated` one; both halves of that rule are the loader's (a `graduation-threshold-shape` diagnostic), because this engine's schema subset has no conditional keyword and a rule stated in a keyword nothing enforces is contract drift wearing the appearance of a check. An eligible category with no threshold would be graduation-eligible against no bar at all."
+        },
+        "gloss": {
+          "type": "string",
+          "description": "What edits fall in this category — prose is navigation, never the fact."
+        },
+        "warrant": {
+          "type": "string",
+          "pattern": "\\S",
+          "description": "Why this category carries this eligibility. For a `gated` category this is the substance: name what judgment the edit requires that no streak of correct instances removes. Must carry actual text, not whitespace."
+        },
+        "decision": {
+          "$ref": "#/$defs/decisionRef",
+          "description": "REQUIRED — the Decisions entry that declared this row (§3.3). The table governs the trust boundary, so a row nobody signed is exactly the ungoverned autonomy the mechanism exists to prevent. Resolved like any other cross-store ref: an id naming no decision is an unresolved-ref error."
+        },
+        "declared": { "$ref": "#/$defs/isoDate" }
+      }
+    }
+  }
+}

package/payload/schemas/knowledge-leaf.schema.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:knowledge-leaf",
+  "title": "Knowledge leaf front matter (PRD §3.2)",
+  "description": "The YAML front matter of one knowledge leaf file; the markdown body below it holds the actual knowledge content. Truth anchor: the world — citation-anchored, human-gated writes only. One leaf per file, so the front matter is the store file and carries schema-version (§3.5) — v2-shape leaves stamp schema-version: 2 (UCS-1147). Every leaf carries an opaque accession id (id: L-NNNNNN), minted at PR time and never reused: it is the leaf's identity, what the loader indexes by, and the ONLY shape a citation of a leaf may take. The dotted `notation` is demoted to an optional legacy display label that nothing treats as identity (UCS-1147, retiring the dual-shape citation contract UCS-1144 opened). Because identity is opaque rather than positional, a leaf file may be moved — between prefix shards, between directories — without invalidating a single citation: position on disk carries no meaning. Cross-reference resolution and catalog-index consistency are structural-validator checks (KK-05). Schema evolution is additive-only (§3.5, D-013), with one sanctioned exception: frontmatter v2 RETIRED the free-prose `description` field (UCS-1149). A leaf now opens its body with a topic sentence and display prose is DERIVED from it, so the one-line summary can never drift from the content it summarizes. Under additionalProperties:false a leaf still carrying `description` fails as an unknown property — a deliberate break, and the major release D-021 defines for exactly this.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema-version", "id", "domain", "heading", "citations"],
+  "properties": {
+    "schema-version": { "type": "integer", "minimum": 1 },
+    "id": {
+      "$ref": "#/$defs/accession",
+      "description": "Accession id — opaque, minted at PR time, never reused, never positional (L-NNNNNN). REQUIRED: it is the leaf's identity, the key the loader indexes by, and the only spelling any record may cite this leaf as (UCS-1147). A leaf without one has no identity, so its absence is a missing-required finding and the remedy is to assign one."
+    },
+    "notation": {
+      "$ref": "#/$defs/notation",
+      "description": "OPTIONAL LEGACY display label — the leaf's old position in the per-project tree (e.g. \"362.1\"), kept so a reader who knows the tree still recognizes the leaf. It is NOT an identity: nothing indexes by it, no citation resolves through it, and moving the leaf's file does not invalidate it. Still validated by pattern when present, because a malformed label is a defect even though nothing resolves through it. Quote it — unquoted it parses as a number."
+    },
+    "domain": {
+      "type": "string",
+      "description": "LEGACY navigational domain — a free string naming the tree branch this leaf files under, paired with `division` and mirrored in the notation spine (§3.2). Ungoverned: nothing checks it against a vocabulary. Distinct from `facets.domain`, which is the REGISTRY-GOVERNED subject path (UCS-1148) whose every segment must be minted. The two coexist while v2 lands; UCS-1149 settles which survives."
+    },
+    "division": {
+      "type": "string",
+      "description": "Legacy navigational subdivision under `domain`, ungoverned in the same way. See the note on `domain`."
+    },
+    "heading": { "type": "string" },
+    "notes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/note" },
+      "description": "Governance notes required by the build skill: scope/class-here."
+    },
+    "cross-references": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "class-elsewhere": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/leafRef" },
+          "description": "Redirects — must resolve. Cite the target leaf by its accession id (L-NNNNNN)."
+        },
+        "see-also": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/leafRef" },
+          "description": "Related context — must resolve. Cite the target leaf by its accession id (L-NNNNNN)."
+        },
+        "including": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Standing room: candidate topics, not authoritative."
+        }
+      }
+    },
+    "citations": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/citation" },
+      "description": "REQUIRED — an unsourced claim is not promotable."
+    },
+    "facets": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Governed facets: values drawn from the store's registries (UCS-1148). Membership is a structural-validator check, never a schema enum — the vocabulary is minted by literary warrant under steward review, so it grows by a registry edit plus a Decisions entry rather than by an engine release.",
+      "properties": {
+        "domain": {
+          "type": "string",
+          "description": "Hierarchical domain path from the domains registry, '/'-joined. Valid only when EVERY segment is minted — a child cannot hang off an unminted parent. This is the GOVERNED subject path, not the legacy top-level `domain` free string: membership here is a structural-validator check against knowledge/_registries/domains.yaml, and the top level of that registry is open (a new class is a registry edit plus a Decisions entry)."
+        },
+        "form": {
+          "type": "string",
+          "description": "What KIND of knowledge this leaf is — reference, recipe, runbook, constraint (UCS-1149). Flat value from the form registry. Ships EMPTY like domains: which forms a project recognizes is a judgement about its own material, so the vocabulary is minted by warrant rather than shipped as an enum."
+        },
+        "anchor": {
+          "type": "string",
+          "description": "The truth anchor this leaf's claim answers to — artifact, world, or team (D-003). Flat value from the anchor registry. That vocabulary is FIXED by the kit rather than chosen per project — the three anchors are the kit's own architecture, and a project minting a fourth would be describing a store this engine does not have — but the registry still ships EMPTY, because every value must cite a Decisions entry that resolves and a seeded repo's decisions store starts empty (D-001). The bootstrap interview mints the three with an entry of the project's own; the registry template's header names them."
+        },
+        "stage": {
+          "type": "string",
+          "description": "Where this leaf sits in its promotion lifecycle — draft until a moderator promotes it, verified once they have (UCS-1149). Flat value from the stage registry: draft, proposed, verified. That vocabulary is FIXED by the kit rather than chosen per project, because the same values drive the shared pre-promotion predicate (isPrePromotionStatus) — a project that renamed them would have a resolver downrank and a preflight verdict disagreeing about which leaves are provisional — but the registry still ships EMPTY, since every value must cite a Decisions entry that resolves and a seeded repo's decisions store starts empty (D-001). A draft or proposed leaf is downranked in resolver output and verdicted unknown by preflight, through that one predicate. There is deliberately no deprecated stage yet: no leaf surface implements the demotion the concept lifecycle gives that word, so the term would govern nothing."
+        }
+      }
+    },
+    "verified": {
+      "$ref": "#/$defs/isoDate",
+      "description": "When this leaf's claim was last checked against its citations — the Time facet's date half (UCS-1150). TOP-LEVEL, alongside `volatility`, not under `facets`: a facet is a governed classification of what the leaf IS, drawn from a registry, while this is a governance fact about the record's own upkeep. Paired with `volatility` to produce a pinned trusted/stale verdict, computed ONLY against an injected `--today` — the engine never reads the wall clock (D-012), and without an injected date the check reports itself skipped rather than passing silently. Same calendar-date pattern as every other date in this schema; a date matching the pattern but naming no real day (2026-02-30) is a structural-validator finding, because an age measured from a day that does not exist is a number nobody's calendar agrees with."
+    },
+    "volatility": {
+      "enum": ["static", "stable", "volatile"],
+      "description": "How fast this leaf's subject moves — the Time facet's rate half (UCS-1150). Governs when the leaf stales: `static` never, `stable` after 365 days, `volatile` after 90, measured from `verified`. A SCHEMA ENUM rather than a registry, which is the opposite of how form/anchor/stage are governed and deliberately so: those registries hold values the engine only compares, so a project may mint its own, whereas each value here is a KEY INTO A PINNED NUMERIC TABLE in engine/lib/time-verdicts.js. A project that minted a fourth class by registry edit would produce leaves with no threshold at all — a governed field silently ungoverned, which is the failure class this engine exists to prevent. Extending the vocabulary means shipping a threshold for it, so it is an engine release with a Decisions entry, and the schema is where that is said. ABSENT means the leaf is EXEMPT from time governance, not that it defaults to a class: the facet arrived in v2 and stores are mid-migration, so defaulting would stale every un-migrated leaf in the store at once on the first run that passed --today. Exempt is reported as its own verdict class, never as `trusted` — a leaf nothing governs has not passed a check."
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Who wrote this leaf and with which authoring skill (UCS-1149). Recorded, never judged: no registry governs it, because an author name and a skill version are facts about how the entry came to exist rather than governed vocabulary. Round-trips untouched through resolver and validator output.",
+      "properties": {
+        "author": {
+          "type": "string",
+          "description": "Who authored the entry — a human steward or the agent that drafted it."
+        },
+        "skill-version": {
+          "type": "string",
+          "description": "The version of the authoring skill that produced the entry, so a systematic drafting defect can be traced to the vintage that introduced it."
+        }
+      }
+    },
+    "operations": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Verbs from the operations registry — what this leaf lets a reader DO."
+    },
+    "applies": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Where this leaf's claim holds.",
+      "properties": {
+        "jurisdictions": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Values from the jurisdictions registry."
+        }
+      }
+    },
+    "concepts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/conceptRef" },
+      "description": "Ontology concepts this leaf is knowledge ABOUT (UCS-1151). The edge lives leaf-side because deciding what a leaf is about is curatorial, and the leaf is what sits under the human write gate. It is derived BIDIRECTIONALLY at load: the loader builds concept -> leaves from these declarations, so resolving a concept surfaces its declaring leaves structurally, with no dependence on whether the leaf's `terms` happen to spell the concept's term. Targets must resolve — an unresolvable id is the ordinary unresolved-ref finding, declared in the ref-field table like every other typed edge."
+    },
+    "paths": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Repo-relative file or directory paths this leaf governs (UCS-1151). NOT an id space: these name the working tree, so they are checked against the filesystem as a missing-path finding — the same mechanism concept source-of-truth pointers already ride — rather than through the ref graph, which only knows how to ask whether an ID resolves. Each entry must name something INSIDE this repo that exists: a path resolving outside the repo root (`../elsewhere`, or an absolute path) is refused, because a store may only point at its own repo and an escaping pointer would be judged against a file the store has no claim on. So is a path naming the repo root itself — a pointer at everything attributes nothing. Reverse lookup (resolve --paths) joins over these alongside concept pointers, so the files in a diff surface the knowledge that governs them before an edit."
+    },
+    "relates": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Typed leaf-to-leaf edges (UCS-1151). Four kinds, each a distinct claim about how two leaves stand to one another, and each a declared row in the ref-field table targeting the leaf space. The resolver expands exactly ONE hop over these from any hit, labeled by kind, so a hit carries its structural neighborhood without a second lookup. Targets are leaf refs, which since UCS-1147 means accession ids and nothing else: the dotted notation is a legacy display label and no longer resolves.",
+      "properties": {
+        "depends-on": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/leafRef" },
+          "description": "This leaf's claim is only usable once the target's is — a prerequisite, not a suggestion."
+        },
+        "see-also": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/leafRef" },
+          "description": "Related context worth reading alongside. The weakest of the four: no dependency, no conflict."
+        },
+        "contradicts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/leafRef" },
+          "description": "The two leaves make claims that cannot both hold. Recorded rather than resolved — surfacing the conflict is what lets a human settle it, and a store that hid it would let a reader cite either one unaware."
+        },
+        "supersedes": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/leafRef" },
+          "description": "This leaf replaces the target's claim. Distinct from contradicts: the disagreement is already settled, and this leaf is the settlement."
+        }
+      }
+    },
+    "terms": { "type": "array", "items": { "type": "string" } },
+    "edition": { "type": "integer", "minimum": 1 },
+    "contributors": { "type": "array", "items": { "type": "string" } }
+  },
+  "$defs": {
+    "notation": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)*$" },
+    "accession": { "type": "string", "pattern": "^L-[0-9]{6}$" },
+    "conceptRef": { "type": "string", "pattern": "^K-[0-9]+$" },
+    "leafRef": { "type": "string", "pattern": "^L-[0-9]{6}$" },
+    "isoDate": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "note": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "text"],
+      "properties": {
+        "type": { "enum": ["scope", "class-here", "revision"] },
+        "text": { "type": "string" },
+        "date": { "$ref": "#/$defs/isoDate" }
+      }
+    },
+    "citation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source"],
+      "properties": {
+        "source": { "type": "string" },
+        "accessed": { "$ref": "#/$defs/isoDate" },
+        "authority": {
+          "type": "string",
+          "description": "The source's authority tier, from the authority-tiers registry (UCS-1148). A tier is a governed value, not an enum: which tiers a project recognizes is its own to mint."
+        }
+      }
+    }
+  }
+}

package/payload/schemas/miss.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:unknown-knowledge:schema:miss",
+  "title": "Miss-log fragment (PRD §3.4, §5.2)",
+  "description": "One unextractable anchor recorded in logs/misses/ — ONE FILE PER ENTRY (D-010), so concurrent sessions never merge-conflict; the fragment is the store file and carries schema-version (§3.5). The demand-driven extractor backlog: a shape description, no parser yet. Capture content policy: concept IDs and file paths only — never verbatim user text or secrets; committed fragments are permanent git history. Lifecycle open → proposed → resolved/rejected; recurrences re-open the same entry (never duplicate), appending to occurrences. The reflect skill (KK-22) consolidates fragments and prunes resolved ones; uncorroborated entries age out to archived with a rollup note. Schema evolution is additive-only (§3.5, D-013).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema-version", "date", "path", "shape", "status"],
+  "properties": {
+    "schema-version": { "type": "integer", "minimum": 1 },
+    "date": { "$ref": "#/$defs/isoDate" },
+    "path": {
+      "type": "string",
+      "description": "Root-relative path of the anchor no extractor kind can read."
+    },
+    "shape": {
+      "type": "string",
+      "description": "Shape description of the unextractable anchor — enough for the 6-step new-kind pipeline (§5.2) to draft a parser; paths and structure only, never file contents verbatim."
+    },
+    "session": {
+      "type": "string",
+      "description": "Opaque platform/session hint — an ID, never quoted session content."
+    },
+    "status": {
+      "enum": ["open", "proposed", "resolved", "rejected"],
+      "description": "Lifecycle: open → proposed → resolved/rejected; re-open-not-duplicate."
+    },
+    "verified": {
+      "$ref": "#/$defs/isoDate",
+      "description": "Stamped by the transition helper when the entry resolves (validator re-run passed); removed on re-open."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Required on rejection — rejections record the reason (§8)."
+    },
+    "occurrences": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/isoDate" },
+      "description": "Re-open dates: recurrences re-open the same entry, never duplicate (§8)."
+    }
+  },
+  "$defs": {
+    "isoDate": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }
+  }
+}