tymofiy · tymofiy · May 9, 2026 · Apr 19, 2026 · Apr 28, 2026 · Apr 28, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -10,7 +10,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Setup Node.js
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: "24"
       - name: Setup Python

diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,132 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-FileCopyrightText: 2026 Timothy Kompanchenko -->
+
+# AGENTS.md — start here if you are an AI
+
+> **Audience:** an autonomous AI agent (Claude, GPT, Gemini, local model, etc.) reading this repository for the first time.
+>
+> **Purpose:** route you to the minimum required reading for your specific task, so you don't have to load all ~9,400 lines of spec prose across the 22 spec/*.md files into your context window before doing useful work.
+>
+> If you are a human, [`README.md`](README.md) is the better entry point.
+
+---
+
+## What KP:1 is, in three sentences
+
+KP:1 (Knowledge Pack v1) is a plain-text format for representing **epistemic state** — claims with confidence, evidence, contradictions, and the trace of how beliefs evolved. It is designed to preserve the texture of knowledge (uncertainty, tension, supersession) that ordinary RAG pipelines and structured databases flatten away. The format is text-only, parser-deterministic, and AI-readable — but authoring a sound pack requires producer-side judgment that this repository documents in [`spec/AUTHORING.md`](spec/AUTHORING.md).
+
+## The single example to read first
+
+[`conformance/fixtures/valid/maximal.kpack/`](conformance/fixtures/valid/maximal.kpack/) demonstrates **all the hard features**: the `⊗!` (error) and `⊗~` (productive tension) qualifiers, supersession (`⊘`) chains, cross-pack `↔` references, all six metadata positions in the dense form, and meta-claims. It passes conformance. Read this before reading prose about what those features mean.
+
+The four `examples/` packs are progressively more demanding: `solar-energy-market.kpack` (hello-world; dense + verbose syntax), `kp-external-assessment.kpack` (meta example), `art-acquisition-decision.kpack` (full feature surface; walks AUTHORING.md end-to-end), and `auction-house-consignment-review.kpack` (consigner-side counterpart; cross-pack `↔` references).
+
+---
+
+## Reading order by task
+
+Pick your task. Read the **Required** column. The **Secondary** column is useful if your context window has room. The **Skip** column is unhelpful for your task and you should not load it.
+
+| Your task | Required reading | Secondary | Skip |
+|---|---|---|---|
+| **A. Parse / validate an existing pack** | [`spec/CORE.md`](spec/CORE.md), [`conformance/grammar/kp-pack.schema.json`](conformance/grammar/kp-pack.schema.json), [`conformance/grammar/kp-claims.peg`](conformance/grammar/kp-claims.peg) | `conformance/fixtures/` (worked examples); [`spec/ARCHIVE.md`](spec/ARCHIVE.md) **if your parser handles sealed `.kpack` archives**; [`spec/COMPOSITION.md`](spec/COMPOSITION.md) **if your parser handles composition packs** (which may omit `evidence.md` and have narrative `claims.md`) | `spec/SPEC.md`, `spec/RATIONALE.md`, other companions |
+| **B. Author a new pack** | [`spec/CORE.md`](spec/CORE.md), [`spec/AUTHORING.md`](spec/AUTHORING.md), [`conformance/fixtures/valid/maximal.kpack/`](conformance/fixtures/valid/maximal.kpack/), [`examples/art-acquisition-decision.kpack/`](examples/art-acquisition-decision.kpack/) (walks the rubrics end-to-end) | [`spec/EXTENSIONS.md`](spec/EXTENSIONS.md) for `extensions.*` payloads; [`spec/RATIONALE.md`](spec/RATIONALE.md) §3 specifically for the **Stranger Test** and the Why-it-exists rationale on `display.short_title` / `tagline` / `hook` / `hint` (the rest of RATIONALE.md is positioning and can be skipped for authoring) | `spec/SPEC.md` (full normative — useful only for hard cases CORE.md doesn't cover), `conformance/run.py` (validator internals) |
+| **C. Reconcile two packs with contradictory claims** | [`spec/RECONCILIATION.md`](spec/RECONCILIATION.md) (it is a stub by design — read it to understand the deferral), [`spec/CONSISTENCY.md`](spec/CONSISTENCY.md), [`spec/CORE.md`](spec/CORE.md) (relation symbols including cross-pack `↔`) | [`spec/AUTHORING.md`](spec/AUTHORING.md) §4 "Contradiction Qualifiers" — note: §4 covers single-pack contradictions; cross-pack composition syntax is not specified in v0.8.0-preview | **For v0.8.0-preview, do NOT produce a "reconciled" canonical pack.** Cross-pack reconciliation is deliberately deferred (see RECONCILIATION.md). Instead: produce an annotated comparison/consistency report that surfaces the disagreement to a human reviewer, using `↔packB#claim-id` cross-pack references and the single-pack `⊗!` / `⊗~` rubric where applicable. The canonical "compose two packs into one reconciled pack" protocol does not exist yet. |
+| **D. Translate a pack into a second locale** | [`spec/MULTILINGUAL.md`](spec/MULTILINGUAL.md), [`spec/CORE.md`](spec/CORE.md) §10 (Views) | [`spec/VOICE.md`](spec/VOICE.md) if voice views are involved | `spec/SPEC.md`, `conformance/`, all companions except MULTILINGUAL/VOICE |
+| **E. Compose a meeting / briefing pack from existing packs** | [`spec/COMPOSITION.md`](spec/COMPOSITION.md), [`spec/CORE.md`](spec/CORE.md) | [`conformance/fixtures/valid/composition.kpack/`](conformance/fixtures/valid/composition.kpack/); [`spec/LIFECYCLE.md`](spec/LIFECYCLE.md) §6 (supersession cascade — relevant when a composed standing pack supersedes a claim the meeting pack referenced) | `spec/SPEC.md`, the rest |
+| **F. Self-driving voice playback of a pack** | [`spec/PLAYBACK.md`](spec/PLAYBACK.md), [`spec/VOICE.md`](spec/VOICE.md) | [`spec/CORE.md`](spec/CORE.md) §10 | All other companions |
+
+If your task is none of A–F, default to **Task B** reading set and judge from there.
+
+---
+
+## Validate your own pack
+
+```bash
+# From the repo root, after cloning:
+pip install -r requirements.txt
+
+# Validate a single pack:
+python3 conformance/run.py --pack path/to/my-pack.kpack
+```
+
+Or in Python directly:
+
+```python
+import sys; sys.path.insert(0, 'conformance')
+from run import validate_pack
+errs = validate_pack('path/to/my-pack.kpack')
+if errs:
+    for e in errs: print(e)
+else:
+    print("PASS")
+```
+
+To run the full conformance suite (19 fixture + example tests):
+
+```bash
+python3 conformance/run.py
+```
+
+If validation fails, the runner names the **semantic constraint** (`SC-01` … `SC-12`) or **ambiguity resolution** (`AR-01` … `AR-16`) you violated. Look those up in [`spec/CORE.md`](spec/CORE.md) §12 and Appendix B.
+
+---
+
+## What you MUST NOT do
+
+These rules are absolute. They are the most common ways a fresh agent breaks the format.
+
+1. **MUST NOT translate `claims.md`.** Claims are always American English (per [`spec/MULTILINGUAL.md`](spec/MULTILINGUAL.md) §2 P1). Translations live in `views/{locale}/`. The single normative exception is `extensions.translations` for evidentiary multilingual domains (see MULTILINGUAL.md §12) — translations there are audit trail, not co-canonical claims.
+
+2. **MUST NOT omit the Rosetta header** at the top of `claims.md`. Without it, conformance fails immediately. Copy from any fixture under `conformance/fixtures/valid/`.
+
+3. **MUST NOT mix dense and verbose claim metadata within a single claim** ([`spec/CORE.md`](spec/CORE.md) AR-13). A claim uses either `{conf|type|ev|date|...}` (dense) OR `` `confidence: ... | type: ... | ...` `` (verbose). Not both.
+
+4. **MUST NOT default to `⊗~` (productive tension) for every contradiction** to avoid making a judgment call. The whole point of the qualifier is to distinguish *known wrong* (`⊗!`) from *both informative* (`⊗~`). See [`spec/AUTHORING.md`](spec/AUTHORING.md) §"Contradiction Qualifiers" for the decision rubric.
+
+5. **MUST NOT emit `0.99`+ confidence by default.** Reserve confidence ≥0.99 for trivially-falsifiable claims (e.g., "this PDF contains the string 'X'"). For everything else, the volume and quality of evidence determines the value within a Sherman Kent band — see [`spec/AUTHORING.md`](spec/AUTHORING.md) §5 "Confidence Calibration".
+
+6. **MUST NOT edit a claim in place after a pack version has been sealed.** Use `⊘` (supersedes) to replace; the original moves to `history.md`. The audit trail is the format's value proposition.
+
+7. **MUST NOT add fields to PACK.yaml that are not in the schema** ([`conformance/grammar/kp-pack.schema.json`](conformance/grammar/kp-pack.schema.json)). The manifest root is closed. Producer-defined metadata goes under `extensions.*` (see [`spec/EXTENSIONS.md`](spec/EXTENSIONS.md)).
+
+8. **MUST NOT translate or alter the syntactic operators (`→ ⊗ ⊗! ⊗~ ← ~ ⊘ ↔`) when localizing**. They are part of the syntax, not the prose. Translate the claim text only.
+
+---
+
+## What you can ignore
+
+These exist in the repository but are not load-bearing for any of Tasks A–F:
+
+- `positioning/` — public-facing positioning material, not normative
+- `research/` — benchmark design and prior-art analysis, not normative
+- `decisions/` — decision records, useful for understanding *why* but not *what*
+- `scripts/` — git hooks and validation helpers, not normative
+- `reference/` — `reference/kpack` is a contract-pointer stub for the planned `kpack` CLI (run it to see which spec section defines each subcommand); the actual reference parser/tooling ships separately
+- `GOVERNANCE.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `LICENSE*`, `DCO.txt` — governance, not format
+
+---
+
+## Status as of v0.8.0-preview
+
+The KP:1 specification is an **editor's draft**. The substantive format (claim grammar, manifest schema, conformance suite) is stable. Some companion documents are explicit stubs:
+
+- [`spec/RECONCILIATION.md`](spec/RECONCILIATION.md) — concept-only stub. Full design deferred to v0.9 / v1.0 contingent on observing real cross-pack drift in ≥3 packs.
+- [`spec/PLAYBACK.md`](spec/PLAYBACK.md) — experimental. Schema may evolve before v0.9.
+
+The CLI tool sketches in `spec/SPEC.md` §13 (`kpack render`, `kpack reconcile`, `kpack lint`, etc.) describe **planned reference tooling**. The only command that exists today is `python3 conformance/run.py`. A contract-pointer stub at [`reference/kpack`](reference/kpack) tells you which spec section defines each subcommand's contract — run `./reference/kpack <subcommand>` to find out where to look. References to `kpack <command>` in the spec should be read as "the eventual reference tool will offer this command" — they are not currently runnable.
+
+---
+
+## If something seems wrong
+
+The four most common false alarms when an agent first reads this repo:
+
+1. **"The Quick Start example seems to be missing X."** It probably is intentionally minimal. Read [`conformance/fixtures/valid/maximal.kpack/`](conformance/fixtures/valid/maximal.kpack/) for the full feature surface.
+2. **"CORE.md and SPEC.md disagree."** Where they appear to disagree on the implementable surface, **CORE.md wins** (per [`spec/README.md`](spec/README.md) "Three normative lanes"). SPEC.md provides surrounding rationale.
+3. **"I cannot find a decision rule for X."** Check [`spec/AUTHORING.md`](spec/AUTHORING.md) first — that file is the producer-side rubric. If it isn't there, the spec genuinely does not yet specify it; report this as feedback rather than inventing one.
+4. **"The conformance runner says my pack is invalid but I don't see why."** The error message names a specific `SC-NN` or `AR-NN`. Search [`spec/CORE.md`](spec/CORE.md) for that exact identifier; the rule and rationale are co-located.
+
+---
+
+*This file is a navigation aid, not a normative document. Where it conflicts with [`spec/CORE.md`](spec/CORE.md), CORE wins.*
diff --git a/CITATION.cff b/CITATION.cff
@@ -2,13 +2,20 @@ cff-version: 1.2.0
 message: "If you reference KP:1 in academic or technical work, please cite as below."
 title: "KP:1 — Knowledge Pack Format Specification"
 abstract: >
-  KP:1 is a text-native specification for representing epistemic state
-  (beliefs, confidence, evidence, contradictions) in AI workflows. It is
-  designed for inspectability and portability with a strict core and
-  explicit extension profiles.
+  KP:1 is a text-native specification for representing epistemic state —
+  claims with confidence, evidence, contradictions, and the trace of how
+  beliefs evolved — designed for AI inspectability and portability across
+  systems. The format defines a strict normative core (CORE.md, JSON
+  Schema, PEG grammar) plus a set of topic-authoritative companions for
+  voice surfaces, multilingual support, archival, composition, and
+  extension blocks. Distinguishing features include typed contradiction
+  qualifiers (⊗, ⊗!, ⊗~), a Voyager-Principle Rosetta header for
+  zero-dependency parsing, supersession semantics with append-only
+  history, and a three-surface architecture (claims for AI reasoning,
+  display views for visual reading, voice views for spoken delivery).
 type: software
-version: "0.7-preview"
-date-released: "2026-04-06"
+version: "0.8.0-preview"
+date-released: "2026-05-09"
 authors:
   - family-names: "Kompanchenko"
     given-names: "Timothy"
@@ -18,14 +25,29 @@ license-url: "https://creativecommons.org/licenses/by/4.0/"
 repository-code: "https://github.com/tymofiy/kp"
 keywords:
   - knowledge representation
+  - knowledge pack
   - epistemic state
   - AI specification
-  - confidence
-  - evidence
+  - confidence calibration
+  - evidence reference
+  - contradiction qualifiers
+  - claim grammar
+  - PEG grammar
+  - JSON Schema
+  - RFC 2119
+  - Sherman Kent confidence scale
+  - Rosetta header
+  - Voyager Principle
+  - text-native format
 identifiers:
   - type: doi
     value: "10.5281/zenodo.19445263"
-    description: "Zenodo DOI for the v0.7-preview release"
+    description: >
+      Zenodo DOI for the v0.7-preview release (the previous public preview).
+      The v0.8.0-preview release described by this CITATION file will be
+      deposited to Zenodo as a separate DOI under the same concept-DOI
+      umbrella; until that deposit is published, this DOI references the
+      predecessor release.
   - type: other
     value: "USPTO 99747548"
     description: "United States trademark application for KP:1 (Class 9, intent-to-use, filed 2026-04-06)"
diff --git a/Makefile b/Makefile
@@ -0,0 +1,43 @@
+# KP:1 — convenience targets
+#
+# The conformance runner is the only fully-implemented validator in this repo
+# (per AGENTS.md). This Makefile is a convenience wrapper, not a build system.
+# All targets are reproducible from a fresh clone after `pip install -r
+# requirements.txt`.
+
+PYTHON ?= python3
+PACK   ?=
+
+.PHONY: help install conformance pack lint clean
+
+help:
+	@echo "KP:1 conformance targets"
+	@echo ""
+	@echo "  make install        Install Python dependencies (pyyaml, jsonschema)"
+	@echo "  make conformance    Run the full conformance suite (expects 19/19)"
+	@echo "  make pack PACK=path Validate a single pack at PATH"
+	@echo "  make lint           Same as conformance (alias)"
+	@echo "  make clean          Remove __pycache__ and .pyc files"
+	@echo ""
+	@echo "Examples:"
+	@echo "  make conformance"
+	@echo "  make pack PACK=examples/solar-energy-market.kpack"
+
+install:
+	$(PYTHON) -m pip install -r requirements.txt
+
+conformance:
+	$(PYTHON) conformance/run.py
+
+lint: conformance
+
+pack:
+	@if [ -z "$(PACK)" ]; then \
+		echo "error: PACK is required. Usage: make pack PACK=path/to/your-pack.kpack"; \
+		exit 2; \
+	fi
+	$(PYTHON) conformance/run.py --pack $(PACK)
+
+clean:
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+	find . -type f -name '*.pyc' -delete