Conversation
…optional fields (v0.7.6) Promotes NATO Admiralty grading fields from open-vocabulary (AR-07 accepted-but-ignored) to documented optional fields with normative values: - reliability: A-F (source tier) - credibility: 1-6 (information credibility for this specific fact) Combined A1..F6 is the standard intelligence-tradecraft grade. No breaking changes — both fields remain optional, existing packs parse unchanged. Packs using reliability informally (e.g. "moderate") may continue but SHOULD migrate to the single-letter form for renderer interop. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The KP:1 manifest root remains closed; the `extensions` lane (added in v0.7.4) is the sanctioned compatibility surface for producer-defined metadata. EXTENSIONS.md catalogues the producer-defined extension blocks in active use across the Nova ecosystem so producers and consumers can converge on shared shapes without forcing schema breaks. Documents `extensions.ai_brief` (the v0.7.4 example), `extensions.entities` (typed entity graph), `extensions.relations` (typed edges, mirroring DEFINITIONS.md §3), `extensions.intent` + `intent_schema_version` + `intent_derivation` (decision-frame layer), `extensions.playbook` (runtime trace), `extensions.workspace` (Decision Workspace bookkeeping), and `extensions.research` (free-text research metadata). Cross-cutting sections cover canonical entity ID minting (`ent_<type>_<6-hex>`), recommended `external_ids` vocabulary, and per-claim `entity_refs` / `relation_refs` annotation. Migration notes for `entities.md` → `extensions.entities` and free-text `anchor_subject` → typed entities. README.md lists the new companion document. No core schema change. Consumers MUST ignore unknown extension content per the existing extensions lane contract (CORE.md §1.1, SPEC.md §3.2). Co-Authored-By: Claude <noreply@anthropic.com>
SPEC.md §7 marked deprecated as of v0.7.6. New packs MUST NOT emit entities.md. The replacement surfaces in EXTENSIONS.md §2.2-2.3 carry stable Nova IDs, an external-ID vocabulary suitable for cross-pack resolution, per-claim entity_refs, and the relation_types schema from DEFINITIONS.md §3. The legacy entities.md content is preserved for reference; legacy packs continue to validate against the conformance runner. Used in only five packs out of ~770. The free-text Relationships block was never machine-consumed. Migration handled by a one-shot script in kp-forge that rewrites legacy packs into the new shape. Co-Authored-By: Claude <noreply@anthropic.com>
The relation_types schema at DEFINITIONS.md §3 defines the vocabulary; producers in the Nova ecosystem write instances of relations under extensions.relations in PACK.yaml. New worked example shows a provenance_chain instance with edge_attributes (acquisition_method, sale_price), references entities declared under extensions.entities, and notes that sensitive: true edge attributes (e.g. sale_price) MUST NOT appear in user-facing dossier prose. Wires up what was previously dead spec — the relation_types schema saw no consumer references in any claim or instance pack. Cross-references EXTENSIONS.md §3 for the cross-cutting sensitive-attribute discipline. Co-Authored-By: Claude <noreply@anthropic.com>
Documents the producer-defined extension blocks under extensions.* in active use across the Nova ecosystem: ai_brief, entities, relations, intent, playbook, workspace, research. Retires entities.md (used in only five packs) in favour of typed extensions.entities + relations. No core schema change. The manifest root remains closed. Consumers MUST ignore unknown extension content per CORE.md §1.1 / SPEC.md §3.2. Legacy packs continue to validate. Renumbered from v0.7.6 to v0.7.7 during cherry-pick onto dev: dev's parallel v0.7.6 entry (reliability + credibility evidence fields, dated 2026-04-19) shipped under that number first. Internal references to "pre-v0.7.6 packs" / "v0.7.6 conformance runner" inside this entry updated to v0.7.7 for consistency. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…hor role
Schema-side fixes for two classes of repos/packs/ conformance failures
surfaced in the 2026-04-30 ecosystem audit:
- 11 packs failed display.short_title maxLength=30 because real
canonical names overflow ("Father's Memories - Family Lineage and
War", "LVMH Moët Hennessy Louis Vuitton", "Ministry of Culture and
Strategic Communications of Ukraine", etc.). Bumped the cap to 60.
The field's intent ("constrained display contexts") is preserved — UI
ellipsis at smaller widths is the rendering layer's job, not the
schema's. Description updated to reflect the wider envelope and the
rendering-layer responsibility.
- The peellaert-body-of-work pack legitimately needed `co-author` as an
authorship role (substrate co-authored by Tim and Claude with parallel
Codex/Gemini sessions). Added "co-author" to the role enum.
Fixture suite stays 13/13. Full repos/packs sweep: was 14/844 failing
→ 0/844 after these two schema bumps + pack-side fixes (committed
separately to repos/packs).
Renumbered from "v0.7.6.1" to "v0.7.7.1" during cherry-pick onto dev,
matching the v0.7.7 EXTENSIONS catalogue renumber. Adds the previously
missing CHANGELOG.md entry documenting the schema relaxations.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Establishes the normative architecture explicitly: CORE.md = implementer surface, SPEC.md = full normative spec + rationale + ecosystem, companion documents = topic-authoritative for their domains. Per SYNTHESIS-wave3-spec.md §1, this is the highest-leverage upstream move for the v0.8.0 release: without it, every "does this go in CORE or SPEC or extensions?" debate reignites. Changes: - spec/README.md: replaced "How to Read This" with "Three normative lanes" — paragraph each for CORE / SPEC / companions, with explicit authority relationships. Companions are NORMATIVE for their topic, not merely "extensions" of CORE. - spec/CORE.md: added Lane: line to metadata block pointing back to README.md three-lane overview. - spec/SPEC.md: same. The companion authority rule: where CORE makes a claim, that claim holds; where CORE punts to a companion via "see [COMPANION]" cross-references, the companion carries full normative weight on that topic. CORE alone is NOT sufficient for handling locales, voice, or archive integrity — read the companion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ations
Validation outcome: existing seven blocks have honest status grid against
producer evidence in repos/packs/ (21 ai_brief emitters, 16 research
emitters, 1 intent emitter, 0 each for entities/relations/playbook/workspace).
No promotions or demotions needed.
Status notes refined:
- extensions.research: explicit producer count (~16 packs as of v0.7.7).
New block added:
- extensions.translations (§2.8, active) — evidentiary multilingual
transcripts for the Mariupol pipeline. Carries original-language
(Russian, Ukrainian) transcripts of witness statements as audit trail
without making them co-canonical. The English claim remains the
single normative assertion (per MULTILINGUAL.md §2 P1); transcripts
are evidence-shaped, not claim-shaped. Schema: translations: {
[locale: BCP-47]: { transcript, transcript_format?, source_evidence_id?,
transcribed_by?, transcribed_at? } }. Cross-references the MULTILINGUAL
§13 normative exception forthcoming via WS-M4.
Status policy note: extensions.translations is tagged active despite
having one inaugural producer (Mariupol), below the ≥3-producer
heuristic that gates the active tag elsewhere in this document. The
exception is justified by evidentiary criticality + immediate v0.8.0
ship; the alternative (experimental) would understate the block's
production status. If a future block faces the same tension, this entry
sets the precedent for evidentiary-domain exceptions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds optional manifest-root fields that let a Knowledge Pack point at the specification it conforms to. The cold-receiver scenario is the strongest use case: a sealed .kpack archive arriving at a previously-unfamiliar consumer is, by construction, accompanied by no surrounding context — the file extension is the only signal. Reading PACK.yaml first and following spec_uri lets the consumer learn the format from the pack itself, with no out-of-band coordination. Complements the Rosetta header (the inline self-describing parse hint at the top of claims.md): Rosetta is the minimum-viable parse signal, spec_uri is the discovery pointer to the full normative spec. Changes: - conformance/grammar/kp-pack.schema.json: spec_uri (string, format: uri) and spec_version (string) added to top-level optional properties. - spec/CORE.md §3: spec_uri + spec_version added to Core Optional Fields table; new "Spec Discovery" subsection explaining the Rosetta / discovery-pointer split and producer guidance for sealed archives. - spec/ARCHIVE.md §2: new "Format discoverability" subsection cross- referencing CORE §3 from the archive consumer perspective. Codifies "consumers SHOULD read PACK.yaml first" as the cold-receiver protocol. Default published location: https://github.com/tymofiy/kp. Producers SHOULD include spec_uri + spec_version when packs are intended for ecosystem-wide distribution; internal-only packs MAY omit. When omitted, consumers MAY assume the published reference implementation but MUST treat the assumption as informational, not a guarantee. spec_version is recommended whenever a pack is archived for the long term, so future consumers can validate against the exact spec revision the producer targeted (rather than against a moving "latest" version). Tim's framing (2026-05-09): "Particularly if they receive .kpack file extension, so that they're super clear of what to do." Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bumps version markers from v0.7-preview to v0.8.0-preview across the spec entry points and drops stale "Parent: SPEC.md v0.X" lines from companion docs that have grown self-standing. Changes: - README.md: status banner v0.7-preview → v0.8.0-preview; revision- history paragraph references the v0.7.x preview series and the v0.8.0 buildup in CHANGELOG; conformance fixture count 11 → 13. Citation paragraph updates to v0.8.0-preview (latest tag) while preserving the v0.7-preview Zenodo DOI as historical reference. - spec/SPEC.md: top-level title v0.7 → v0.8.0. - CITATION.cff: version 0.7-preview → 0.8.0-preview, date-released 2026-04-06 → 2026-05-09. v0.7-preview Zenodo DOI tagged "(historical)" pending v0.8.0-preview Zenodo deposit (WS-TAG). Parent-line drops (companion docs): - spec/MULTILINGUAL.md, spec/CONVENTIONS.md, spec/BUNDLE.md, spec/ORGANIZATION.md, spec/CONSISTENCY.md, spec/NOTES.md, spec/STORAGE.md — dropped "> **Parent:** SPEC.md v0.X" lines per HANDOFF.md M3 list. These companions are mature enough to stand alone; the parent-version reference was version pollution that needed bumping every spec release. Retained Parent: lines on ARCHIVE/COMPOSITION/DEFINITIONS/EXTENSIONS/ LIFECYCLE/VOICE — they reference specific section anchors (§5, §3.2, Design Principle 18) that genuinely matter for the cross-reference, not just stale pedigree. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ILINGUAL en-GB & sub-registers Three tightly-related companion-doc additions for v0.8.0-preview readiness. WS-M6 — RECONCILIATION.md stub (NEW companion document). Honors prior v0.8 commitment recorded in workspace memory: explicit placeholder establishing the cross-pack consolidation protocol's intent while honestly admitting the design is deferred to v0.9 / v1.0 contingent on observing measurable drift across at least three real packs. Distinguishes from CONSISTENCY.md (single-workspace patrol that surfaces drift) and LIFECYCLE.md (single-pack claim lifecycle). WS-M8 — VOICE.md register axis. Adds `register` as a recommended metadata header field on voice views with four spec values: plain | curatorial | technical | investor. Composes orthogonally with `pace` (speed) and `register` (diction + emphasis profile). New §4.1 subsection explains each register's intent and notes that `register` is producer-side spec metadata, distinct from app-side AudienceProfile.persona (consumer concept). Cross- references MULTILINGUAL §3.3 for locale-specific sub-registers. WS-M9 — MULTILINGUAL.md en-GB row + Register Sub-distinctions section. Adds en-GB to the language tags table as a mechanical sibling of en-US (spelling and idiom delta, not a full translation). Reserves other en-* tags. New "Register Sub-distinctions" subsection explains how locale-specific sub-registers (Western Ukrainian / Halychyna, Quebec French, peninsular Spanish, MSA vs spoken Arabic) refine within the four VOICE.md primary registers rather than replacing them. Introduces informational `sub_register` voice-view metadata field with reviewer- responsibility note: a pack declaring sub_register MUST be reviewed by a native speaker of that sub-register. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…n release Comprehensive entry covering the v0.8.0-preview workstreams that landed in dev across this push: three-lane normative architecture (M1), EXTENSIONS validation pass + extensions.translations (M5), spec_uri/spec_version self-discovery fields (M-spec-uri), version drift sweep + companion Parent: line cleanup (M3), RECONCILIATION stub (M6), VOICE register axis (M8), and MULTILINGUAL en-GB row + sub-registers (M9). Categorized as Added / Changed / Compatibility / Notes per existing CHANGELOG conventions. The entry is comprehensive — every line of new normative material lands here so a future reader has a single high-level entry point into v0.8.0's surface area without reading every commit. Final v0.8.0 (non-preview) is tied to (a) the deferred RECONCILIATION design after ≥3 observed drift instances, and (b) the remaining iPad and Mariupol implementation tracks shipping against the spec. Recorded in Notes section of the entry. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
NEW companion document specifying the spec layer for self-driving voice presentations of Knowledge Packs. Status: experimental for v0.8.0-preview; schema may evolve before v0.9 based on observed renderer behavior. PLAYBACK sits one layer above VOICE.md: where VOICE governs pre-rendered prose artifacts (nouns), PLAYBACK governs dynamic narration (a verb) — a runtime composition that selects, sequences, and delivers pack content phase-by-phase, tuned to the listener via AudienceProfile. Schemas: - AudienceProfile (familiarity / duration_tier / purpose / domain_lens / register / inferred) — listener-specific context passed once at session start. Composes with VOICE.md producer-side register: producer-side controls how voice views are written; AudienceProfile.register is the session-time selection. - PlaybackPlan (pack_id / audience_profile / duration_tier / phases[] / resume_policy / handoff_policy) — deterministic planner output. Each phase has source_refs into pack content (claims / evidence / views / extensions paths), transition_intent (opening / emphasis / building / qualifying / closing), word_budget, and min_tier so one plan covers short/medium/long via filtering rather than three separate plans. Discovery dialogue (3 short questions) with explicit defaults for "just play it" / "short version" / returning-user paths. Normative rules: - Rule P1: language model MUST NOT have a phase-advancement tool. Phase advancement is app-owned. Model MAY have audience-profile capture and view-navigation tools. - Rule P2: only the real-time voice pipeline's actor sends create/cancel response messages. Only the playback controller decides current phase. Stale calls verify epoch before mutating state. Pack-play vs library-play: same schema, different planners. Library-play is triage, not concatenation — selects across packs with cross-pack framing rather than producing a synthetic mega-pack. README.md companion table updated to add PLAYBACK + RECONCILIATION rows. Per Thread D's locked decisions D1-D13 in sessions/2026-05-09-kpviewer-perplexity-study/MASTER-PLAN.md and the SYNTHESIS-wave3-spec.md §4(c) outline. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…able Pairs with the PLAYBACK.md companion just landed and the RECONCILIATION.md stub from the v0.8.0-prep batch. The companion table in spec/README.md is the discovery surface; both new files now appear there. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codifies the normative exception to Core Principle P1 (claims are always
English). For evidentiary multilingual domains — handwritten witness
statements, foreign-language press, court records — original-language
transcripts MAY ship in extensions.translations (EXTENSIONS.md §2.8) as
audit trail. The English claim remains the single normative assertion;
the transcript is evidence-shaped, not claim-shaped.
Codified as the only sanctioned location for non-English text whose
canonicalization to English would lose evidentiary fidelity. Pack
producers SHOULD also acknowledge the language in evidence.md prose for
reader-legibility.
Scope limit explicit: this exception is for *evidentiary* multilingual
domains where the original language is the source of truth. It does NOT
re-open the door to co-canonical multilingual claims (rejected in D1)
or convenience-translation prose (which belongs in views/{locale}/).
Inaugural producer: kilimanjaro-intake's Mariupol corpus.
Decision Log gains D1a entry codifying the exception's rationale and
its relationship to the rejected alternatives. Cross-references
EXTENSIONS.md §2.8.
This is the spec-side completion of the M4 workstream from the
2026-05-09 master plan. Pairs with the EXTENSIONS.md §2.8
extensions.translations block already shipped in WS-M5.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ss-refs Cross-reviewer consensus follow-up to the 2026-05-09 master-plan release. Four independent reviews plus internal audit converged on the same set of mechanical defects this commit addresses. None of the v0.8.0-preview substantive decisions are touched — only pre-existing drift, syntax errors in pedagogical examples, and follow-through on WS-M3 that the original sweep missed. Numbering / cross-refs: - MULTILINGUAL.md §13 ↔ §12 swap (Evidentiary exception now §12, Decision Log §13). EXTENSIONS.md §2.8 cross-ref updated; "(forthcoming)" parenthetical removed. - EXTENSIONS.md Parent line: CORE.md §1.1 → §3 (correct section). Version drift sweep — Path B follow-through: - VOICE, ARCHIVE, LIFECYCLE: bare `Parent: SPEC.md vX` lines dropped (no anchor → no version reference). - COMPOSITION, DEFINITIONS: version pin removed; section anchor retained. - CORE: `Derived from: SPEC.md v0.7` → `SPEC.md` (drop pin). - SPEC: `(v0.4)` and `(v0.6)` section header pins removed. Pedagogical examples — fixes for examples that wouldn't pass conformance: - SPEC.md Quick Start: missing Rosetta header restored. Re-materialized through `conformance/run.py`: PASS. - COMPOSITION.md §3 worked example: ASCII relations (-> * <- ~ / <->) → KP symbols (→ ⊗ ← ~ ⊘ ↔); [M001]-[M005] → [C001]-[C005] per CORE AR-01. - LIFECYCLE.md reconcile-report example: [M001]-[M008] → [C001]-[C008]; EM003/EM004 → E003/E004 per CORE AR-02. Documentation accuracy: - README: fixture count corrected (13 → 11 plus 2 reference examples); pip install bootstrap line added. - ORGANIZATION: directory listing refreshed to include all 19 spec/ files (was missing CORE, README, STORAGE, ARCHIVE, DEFINITIONS, EXTENSIONS, MAPPING, PLAYBACK, RECONCILIATION). - MAPPING: Status: Reference document → Status: Draft (informative) to harmonize sibling vocabulary while preserving normative distinction. - MULTILINGUAL §12 + Decision Log D1a: replaced named-pipeline reference with generic 'witness statements collected in the field' — public spec shouldn't name internal Nova ecosystem identifiers. Conformance: 13/13 passed (unchanged). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…status, EXTENSIONS de-leak KP:1 has framed itself AI-first while packaging itself human-spec-shaped: vocabulary defined everywhere, decision rubrics nowhere. This commit ships the two artifacts the AI-first claim requires, plus an editorial pass on EXTENSIONS.md to remove internal-implementation leakage from the public spec. Added: - AGENTS.md (NEW, repo root) — task-indexed routing for cold AI agents. Covers parse / author / reconcile / translate / compose / playback. Each task names Required reading, Secondary context, and an explicit Skip list, so a fresh agent doesn't burn context window on prose unrelated to its task. Includes a MUST-NOT list distilling the most common failure modes (translating claims.md, omitting Rosetta header, defaulting to one contradiction qualifier for everything, emitting 1.0 confidence by default, mixing dense/verbose claim metadata). - spec/AUTHORING.md (NEW companion) — producer-side decision rubrics. Decision trees + worked examples + anti-patterns for: claim type (o/r/c/i), claim nature (factual/judgment/prediction/meta), contradiction qualifier (bare/error/tension), confidence calibration within Sherman Kent bands, depth (assumed/investigated/exhaustive), supersede vs edit vs split, granularity, and content routing (claims/evidence/views). Hostile-reading sanity checks for the four 'look-fine but degraded' patterns. Worked end-to-end transformation example showing a Reuters/Bloomberg dual-source extraction yielding eight properly typed and calibrated claims. Editorial pass on EXTENSIONS.md: - Internal monorepo paths replaced with public-repo references (kp-forge, kp-packs, kp-viewer remain as named public repositories). - Internal codenames replaced with generic 'reference implementation' and 'field-collected corpus' framing. The public spec no longer leaks internal identifiers. - §2.4 intent enum: softened from closed-MUST framing to 'reference implementation vocabulary; producers MAY define alternative values', resolving the contradiction of a closed enum inside an explicitly informative document. Other: - spec/SPEC.md §13 Tooling: explicit kpack CLI status disclaimer. The kpack commands described in §13 are planned reference tooling, not commands that ship today. Only python3 conformance/run.py is currently runnable. - spec/CORE.md: scope statement (§1) mentions AUTHORING.md; validation.yaml entry in §2 file structure cross-refs SPEC.md §10 schema; AR-10 (Appendix B) gained worked tokenization examples (the relation form vs prose mid-sentence vs the Rosetta legend token). - spec/README.md: companion table now lists AUTHORING.md as the first topic-authoritative entry; footer points AI agents at AGENTS.md. - README.md: 'See also' link list now includes AUTHORING.md and AGENTS.md. - spec/CHANGELOG.md v0.8.0-preview entry: Added/Changed sections expanded to cover the new files, the kpack-CLI disclaimer, EXTENSIONS de-leak, AR-10 examples, and the prior cleanup commit's drift follow-through. Conformance: 13/13 passed (unchanged). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…reference example
Anonymized buyer-side decision-support pack for the prospective acquisition
of a mid-twentieth-century European painting. Designed to walk the decision
rubrics from spec/AUTHORING.md end-to-end on a realistic scenario, so a
producer (human or AI) reading the spec can see what good looks like.
Demonstrates:
- All four claim types: 4 observed, 13 reported, 3 computed, 8 inferred
- All three contradiction qualifiers in their proper roles:
- ⊗! C005 over C004 (a prior dating was demonstrably wrong; both records
preserved, the prior moves to history if amended)
- ⊗~ C008 over C007 (the post-1962 provenance is documented and the
1953-1962 gap is documented; the pair is informative, neither claim
is wrong)
- ⊗~ C019 against C017 (the recommendation sits in tension with an
unbounded risk; the tension is the analyst's judgment about offset)
- Supersession: ⊘ C014 over C013 (the 2025 appraisal of EUR 950,000
supersedes the 2023 appraisal of EUR 1,400,000; supersession is recorded
against the dating revision that prompted it)
- Multiple natures: factual (default), judgment (C005, C014, C017, C018,
C019, C022), prediction (C021), meta (C016, C020)
- Multiple depths: investigated (most), exhaustive (C005, C008)
- Confidence calibration spanning 0.45 to 0.99, calibrated to evidence
depth and source quality per AUTHORING.md
- Three views, each genuinely audience-specific:
- overview.md (buyer-facing summary, balanced)
- counsel.md (compliance-facing, audit-trail emphasis)
- voice/briefing.md (~90s curatorial-register voice briefing)
Pack metadata uses the new spec_uri / spec_version fields from v0.8.0-preview
to demonstrate the cold-receiver discovery pattern.
Conformance:
- conformance/run.py extended to validate the new pack alongside the
existing two examples (now 14/14 passed; was 13/13).
- README.md updated: examples list extended, fixture/example counts and
14/14 number updated in three places.
- conformance/README.md updated: 13/13 -> 14/14 in three places.
- spec/CHANGELOG.md updated: Added entry naming the new example and
cross-referring to AUTHORING.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two complementary additions, finishing the "exhaust the task list" pass. Added — examples/auction-house-consignment-review.kpack: Anonymized consigner-side decision pack. An auction house reviews a sculpture submitted for consignment; a foundry-mark discrepancy surfaces during specialist review; the committee declines the consignment under its current attribution and lays out conditions for reconsideration. Together with art-acquisition-decision.kpack (added in cd31988), the two examples cover both sides of high-stakes asset-decision support: buyer-side acquisition and consigner-side acceptance/decline. Demonstrates aspects complementary to the buyer-side pack: the decline path, cross-pack ↔ references to hypothetical reference packs, evidence diversity (consignor-supplied documents reviewed against house specialist work), and four audience-specific views including a formal-register consignor decline letter. Added — spec/LIFECYCLE.md §6 Claim Supersession Cascade: Normative rule (L1) for what happens to dependent claims when a parent claim is superseded with ⊘. Dependents linked via →supports, ←requires, or ~refines are reviewed by the editor, not auto- invalidated. Includes rationale (why review-not-auto-invalidate), a worked example showing how three dependent claims under a superseded parent get triaged, and an explicit deferral of cross-pack supersession effects to RECONCILIATION.md (which itself defers the full design to v0.9 / v1.0). Sections 6-9 of LIFECYCLE.md renumbered to 7-10 to accommodate the new section. No content changes to those sections. Other: - conformance/run.py: auction-house-consignment-review.kpack added to the auto-validated examples list. - README.md, spec/CHANGELOG.md, conformance/README.md: counts updated (14/14 -> 15/15; 3 examples -> 4). - LIFECYCLE.md §5: planned-tooling disclaimer added to the kpack command list, mirroring SPEC.md §13. Conformance: 15/15 passed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ec/RATIONALE.md
The 1996-line SPEC.md interleaved rationale, philosophy, and positioning
with the implementer-facing surface. This commit extracts three
rationale-only sections into a new informative companion, leaving SPEC.md
shorter and more focused on what an implementer needs.
Added:
- spec/RATIONALE.md (NEW informative companion). Status: Draft
(informative — not normative for KP:1 conformance). Houses:
- §1 Design Principles — the 25 numbered principles that informed
the format's choices (Voyager Principle, append-only, three-surfaces,
locale-first, knowledge-not-journal, constitutional core, etc.).
- §2 Style Systems — the rationale for keeping style systems external
to KP:1, the recommended PACK.yaml `style` field shape, the
style-system YAML schema, and the renderer-pipeline diagram.
- §3 Relationship to Existing Standards — how KP:1 sits relative to
AGENTS.md, llms.txt, SKILL.md, MCP, JSON-LD/RDF, Nanopublications.
Bifurcated:
- spec/SPEC.md §15 Design Principles — the 25-principle list moved to
RATIONALE.md §1; SPEC.md §15 is now a one-paragraph stub linking
forward.
- spec/SPEC.md §17 Style Systems — body moved to RATIONALE.md §2;
SPEC.md §17 retains only the brief PACK.yaml `style` field reference
needed in-place.
- spec/SPEC.md §20 Relationship to Existing Standards — moved to
RATIONALE.md §3; SPEC.md §20 is now a one-paragraph stub.
- spec/DEFINITIONS.md — single cross-reference from "SPEC.md §15,
Principle 5" updated to "RATIONALE.md §1, Principle 5".
Deferred:
- spec/SPEC.md §18 (Cognitive Perception Layer). The §18 content is
hybrid — partly normative (the `display` block field semantics, the
fallback hierarchy) and partly rationale (the Why-it-exists boxes,
the Stranger Test, perception stages). Clean bifurcation requires
consolidating the normative pieces into §3 manifest fields and moving
the rationale into RATIONALE.md §4. That editorial work is deferred
so the bifurcation pattern can ship without destabilizing §18. The
deferral is documented inline in RATIONALE.md.
Doc cross-references updated:
- spec/README.md companion table: RATIONALE.md added.
- spec/ORGANIZATION.md spec/ directory listing: RATIONALE.md added.
- AGENTS.md task-reading map: RATIONALE.md added to the Skip column for
Tasks A (parse) and B (author) — it is informative-only and not
needed for parser/author work.
- spec/CHANGELOG.md v0.8.0-preview entry: Added entry for RATIONALE.md
+ new "Bifurcated" subsection capturing the §15 / §17 / §20 moves.
Size impact:
- SPEC.md: 1996 → 1895 lines (-101).
- RATIONALE.md: 0 → 189 lines.
- Net normative-prose footprint reduced; informative content is
separately addressable.
Conformance: 15/15 passed (unchanged).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…refs grammar, P1 scope Six small revisions across README, CORE, ARCHIVE, MULTILINGUAL, and PLAYBACK to make the v0.8.0-preview normative surface internally consistent before tag. 1. **README.md three-lane intro.** "A correct implementation reads from all three" contradicted the next paragraph saying CORE is sufficient for a parser. Revised to "a conformant implementation reads the lanes relevant to the surfaces it implements" — a parser need only consult CORE; renderers handling voice, locales, or sealed archives read the relevant companions in addition. 2. **ARCHIVE.md §2 Format discoverability.** Reframed `spec_uri` as informational onboarding pointer rather than load-bearing parse signal. "Producers MAY declare" → "Sealed-archive producers SHOULD declare." Added explicit invariant: consumers MUST NOT treat unreachability of `spec_uri` as a parse failure. Clarified that the Rosetta header is the offline parse signal and the archive remains parseable without any network reach. Tightened the closing paragraph to make clear the network dependency (if any) is onboarding-only, not runtime. 3. **CORE.md "Spec Discovery" → "Spec Onboarding Pointer".** Renamed the subsection so the field's intent is unambiguous from the heading. Added a blockquote invariant: consumers MUST NOT treat unreachability or absence of `spec_uri` as a parse failure; offline-first validators MUST function without ever resolving it. `spec_uri` exists to onboard a fresh consumer that has never seen KP:1 — a one-time convenience, not a runtime requirement. Once the consumer has internalized the format, the field carries no further operational weight. 4. **MULTILINGUAL.md §2 P1 cross-reference.** Added explicit "see §12 for the single sanctioned audit-trail carrier exception" so readers landing on the canonical-English principle don't have to discover §12 separately. The exception narrows P1 in one well-defined case (evidentiary multilingual transcripts in `extensions.translations`); the cross-ref makes that scope visible from P1's own paragraph. 5. **PLAYBACK.md source_refs grammar (NEW §4.1, normative).** Previously the spec listed source-ref formats inline in the schema table but did not constrain the grammar. Validators accepted any non-empty string. Added a §4.1 "Source-ref grammar (normative)" with a regex grammar, prefix table, and producer/ consumer responsibilities. Validators MUST reject plans whose `source_refs` entries don't match the grammar. Also added `history.<ID>` to the source-ref vocabulary (was missing — a playback plan must be able to narrate why a claim was superseded, which means referencing history.md entries). Existing §4.1 "Form variants" renumbered to §4.2. 6. **PLAYBACK.md Rule P1 wording.** Reframed from "the language model MUST NOT have a phase-advancement tool" to "a KP:1- conformant renderer MUST NOT expose a phase-advancement tool to the language model" — clearly a renderer constraint, properly scoped. Added a conformance escape: a renderer that does expose such a tool MUST document the non-conformance and SHOULD NOT advertise PLAYBACK conformance. Section title changed accordingly: "app-owned, not model-decided" → "renderer-owned, not model-decided." This is the interop contract between composer and renderer — a plan emitted by one composer renders identically across conformant renderers. Numbering integrity verified: PLAYBACK §4.1 → §4.2 renumber breaks no internal cross-reference (all "§4.1" mentions in PLAYBACK point at VOICE.md §4.1, a different file). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ck stub Three cleanup items completing the bifurcation pass. §18 Cognitive Perception Layer split: - spec/SPEC.md §18 retains the normative contract — the `display` block field list (short_title, abbreviation, tagline, hook), the per-view `hint` field, the field-vs-purpose-vs-display_as table, and the fallback hierarchy a renderer needs. - spec/RATIONALE.md §4 (NEW) takes the rationale — the four perception stages with timed budgets, Why-each-field-exists boxes for short_title / abbreviation / tagline / hook / hint, the Stranger Test, the Good/Bad authoring tables, and the "what these fields are NOT" guidance. - The earlier deferral note in RATIONALE.md is removed; §18 is now cleanly bifurcated. Cross-reference sweep: - Every "(Principle N)" / "(SPEC.md §15, Principle N)" / "(SPEC.md §17)" / "(SPEC.md Principle N)" reference in the rest of the spec corpus updated to point at the corresponding RATIONALE.md location. Files touched: spec/COMPOSITION.md, spec/CONSISTENCY.md, spec/LIFECYCLE.md, spec/STORAGE.md, spec/SPEC.md (one self-reference). DEFINITIONS.md was already updated in the prior bifurcation commit. reference/kpack contract-pointer stub: - New executable Python script. Running `./reference/kpack` lists every subcommand the spec describes (lint, render, reconcile, translate, bundle, archive, new, compose, patrol, promote, restore, play, test, export) with the spec section that defines each contract. - Running `./reference/kpack <subcommand>` prints a one-paragraph summary of that contract, with a clear "this command is not yet implemented" note. - The stub closes the "fictional CLI" critique with a concrete pointer rather than just a disclaimer. The only fully-implemented validator in this repo remains `python3 conformance/run.py`. - reference/README.md updated to describe the stub. - spec/SPEC.md §13 disclaimer updated to point at the stub. - AGENTS.md disclaimer updated to point at the stub. - spec/CHANGELOG.md v0.8.0-preview entry: Bifurcated subsection expanded; new Tooling subsection documents the stub. Size impact: - spec/SPEC.md: 1895 -> 1783 lines (-112). - spec/RATIONALE.md: 189 -> 293 lines. Conformance: 15/15 passed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pre-tag cleanup pass applying eight specific items from the maintainer's own holistic review of the dev branch. None of the substantive v0.8.0-preview decisions changes; these are precision improvements that make external review sharper. 1. spec/SPEC.md §13 — section retitled to "Tooling (planned reference CLI)" and a "# Planned reference tooling — not currently shipped" comment added to the top of both kpack bash blocks. The disclaimer at the top of §13 is good but a reader landing directly on a command table could miss it; the per-block comment is hard to miss. 2. examples/auction-house-consignment-review.kpack/claims.md — added an inline note to the Cross-References section explaining that the two ↔ pointers (foundry-marks-paris-1925-1960, sculptor-y-attribution-research) are illustrative placeholders demonstrating the cross-pack reference grammar; the target packs do not exist in this repository's examples/. 3. spec/AUTHORING.md §1 — softened "treat this document as the producer-side conformance contract" to "producer-side authoring guide", with explicit "AUTHORING.md is informative, not normative; the parser does not check it" qualifier. AUTHORING.md is marked Status: informative; the previous "conformance contract" framing pattern-matched as normative and could confuse a reviewer. 4. spec/PLAYBACK.md §10 — softened "the runtime SHOULD honor sub_register" to "the runtime MAY honor sub_register; it MUST not depend on its presence and SHOULD not treat its absence as an error." sub_register is informational per MULTILINGUAL.md §3.3 (not a normative enum); PLAYBACK's prior SHOULD over an informational field was a subtle inconsistency. 5. spec/RATIONALE.md — reordered §3 and §4 to match the original SPEC.md sequence (§15 Principles → §17 Style → §18 Cognitive Perception → §20 Relationship). RATIONALE.md is now §1 Principles → §2 Style → §3 Cognitive Perception → §4 Relationship to Existing Standards. Cross-references in spec/SPEC.md, spec/CONSISTENCY.md, and spec/CHANGELOG.md updated to match. 6. spec/CORE.md §2 Pack Structure — added an explicit composition-pack exception note. The conformance runner has hardcoded composition-pack special-casing (composition.yaml present → evidence.md not required, narrative claims.md allowed); SPEC.md §2 documents this; CORE.md previously did not. The note carves out the exception in CORE and points at SPEC.md and COMPOSITION.md for detail. 7. spec/DEFINITIONS.md §3 — added a "See also" cross-reference at the top of the Definition Schema section pointing at EXTENSIONS.md §3.1 for the canonical entity-instance ID format. DEFINITIONS.md governs entity *types* (vocabulary); EXTENSIONS.md §2.2 governs entity *instances*. The split was clear in EXTENSIONS but DEFINITIONS lacked the forward pointer. 8. AGENTS.md Task A row — moved spec/ARCHIVE.md and spec/COMPOSITION.md from "Skip" to "Secondary" with conditional language. A parser handling sealed .kpack archives needs ARCHIVE.md; a parser handling composition packs needs COMPOSITION.md. The previous Skip-list was too aggressive for parsers covering those surfaces. Conformance: 15/15 (unchanged). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three places still said "two" example packs after the cd31988 + 0b82658 additions brought the count to four: - README.md repository structure table: "Two complete `.kpack` examples" -> "Four complete `.kpack` reference examples (validated by the conformance suite)". - README.md Examples section heading: "Two complete Knowledge Packs demonstrate the format:" -> "Four complete Knowledge Packs demonstrate the format:". - examples/README.md: rewritten end-to-end. Lists all four packs with feature coverage; explains where to start; documents what each pack demonstrates; updates the validation count to 15/15. Conformance: 15/15 (unchanged). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…udit
Second-pass cleanup after a deep audit surfaced items the first pass missed.
None of the substantive v0.8.0-preview decisions changes; precision and
internal-consistency improvements only.
S-tier (would land badly publicly):
1. spec/CORE.md AR-14 — was "composition.yaml schema deferred to Phase C2".
The schema actually exists at conformance/grammar/kp-composition.schema.json
but the runner doesn't currently invoke it. AR-14 now honestly says so:
"schema is published (informative); the runner detects composition packs
by composition.yaml presence but does not currently validate them
against the published schema."
2. spec/CORE.md header — Status / Date refreshed from "2026-04 / 2026-04-04"
to "2026-05 (v0.8.0-preview) / 2026-05-09" to match README.md and
CITATION.cff.
3. spec/SPEC.md title and header — "v0.8.0" → "v0.8.0-preview"; same
header refresh.
4. spec/CORE.md Scope (§1) and Appendix C, plus spec/SPEC.md §19 — all three
companion lists were missing AUTHORING, RATIONALE, EXTENSIONS, ARCHIVE,
PLAYBACK, RECONCILIATION, MAPPING. Now enumerate all 19 spec/*.md files
with one-line "covers" / "when you need it" descriptions, distinguishing
normative from informative companions.
5. examples/art-acquisition-decision.kpack/PACK.yaml +
examples/auction-house-consignment-review.kpack/PACK.yaml — display_as
field was set to type-token values ("page" / "voice"). Schema permits
any string but the maximal.kpack fixture uses prose labels ("Overview",
"Voice Briefing"); the type-token usage was the only place in the
repository teaching a reviewer "display_as is an enum-like field".
Updated the new packs to use prose: "Overview" / "Counsel Review" /
"Voice Briefing" / "Committee Decision" / "Specialist Notes" /
"Consignor Letter".
M-tier (credibility cost):
6. spec/CORE.md §2 file structure — entities.md row updated from "OPTIONAL
— entity definitions" to "DEPRECATED (since v0.7.4) — use
extensions.entities; see EXTENSIONS.md". The deprecation was already
recorded in SPEC.md §7 and EXTENSIONS.md but CORE.md (the implementer
surface) was silently teaching it as current.
7. AGENTS.md — "The two examples/ packs ..." sentence updated to describe
all four packs progressively. The earlier commit fixed the README count
but missed this reference.
8. AGENTS.md Task B Required reading — added pointer to
examples/art-acquisition-decision.kpack as the worked rubric demo.
Secondary now includes RATIONALE.md §3 for the Stranger Test and the
Why-it-exists rationale on display fields. (RATIONALE.md was previously
in the Skip column, but §3 is the canonical home of the Stranger Test
referenced in CONSISTENCY.md as a normative-grade authoring rule.)
9. examples/auction-house-consignment-review.kpack/claims.md — confidence
values for C004 / C007 / C013 rebalanced from round Sherman-Kent
boundaries (0.83 / 0.87 / 0.91) to two-decimal calibrated values
(0.78 / 0.84 / 0.88). The pack's confidence histogram clustered too
tightly on Sherman Kent edges despite using the simple scale; the
spread now reflects evidence quality rather than band defaults.
10. reference/kpack — added five missing subcommands the spec defines but
the stub didn't list: seal, verify, extract, info (all in ARCHIVE.md
§4-§5), and unbundle (BUNDLE.md). Stub now covers 19 subcommands.
L-tier (editorial polish):
11. spec/CHANGELOG.md — "SPEC.md reduced from 1,996 to ~1,780 lines"
replaced with explicit reduction language; the "~" was sloppy.
12. spec/LIFECYCLE.md, COMPOSITION.md, BUNDLE.md, MULTILINGUAL.md,
VOICE.md, ARCHIVE.md — added a one-line top-of-file disclaimer that
"kpack CLI invocations in this document describe planned reference
tooling. Only python3 conformance/run.py ships today." A reader
landing on a kpack code block deep in any companion now sees the
disclaimer above the block, not after a hundred lines of unguarded
invocations.
13. AGENTS.md — `reference/` line in the "What you can ignore" section
updated to acknowledge `reference/kpack` is now a real (stub) tool,
not the pre-stub placeholder it described.
Deliberately not addressed (your editorial call):
- examples/kp-external-assessment.kpack confidence-hallucination signal
(existing pack, not from this batch).
- author: "Reference Implementation" on the new packs (your call on the
attribution name).
- CITATION.cff DOI mismatch (predecessor's DOI is referenced as historical;
v0.8.0-preview deposit is queued).
- JSON Schema voice-conditional structure (kp-pack.schema.json:342-348)
is non-canonical placement but appears to function; would need a
fixture-level check to confirm.
- CORE.md / SPEC.md heading capitalization differs across the same files
(e.g., "evidence.md — Backing Sources" vs "Evidence Document
(evidence.md)"); minor stylistic.
Conformance: 15/15 passed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Last cleanup pass before publishing the external-review prompt. Goes
through the items deferred from the deep-audit pass and applies the
ones we'd agree on; surfaces verification on the rest.
Items addressed:
1. examples/{art-acquisition-decision,auction-house-consignment-review}.kpack
author field — was "Reference Implementation" (placeholder); now reads
"Timothy Kompanchenko (anonymized demo pack)" with provenance.author
set to the editor's name. Matches the kp-external-assessment pack's
pattern; preserves the demonstration nature in the parenthetical.
2. CITATION.cff — three improvements:
- Abstract expanded from 4 lines to 11 lines describing the format's
distinguishing features (typed contradiction qualifiers, Rosetta
header, three-surface architecture, supersession semantics).
- Keywords expanded from 5 generic terms to 15 load-bearing ones
(added knowledge pack, claim grammar, RFC 2119, PEG grammar, JSON
Schema, Sherman Kent confidence scale, Rosetta header, Voyager
Principle, contradiction qualifiers, etc.). Improves Zenodo +
Google Scholar discoverability.
- DOI description expanded from one line to four, explicitly framing
the v0.7-preview DOI as the predecessor and noting the v0.8.0-preview
deposit is forthcoming under the same concept-DOI umbrella.
3. AGENTS.md and spec/README.md — "9,000+ lines of normative prose"
(vague) replaced with "~9,400 lines of spec prose across the 22
spec/*.md files" (precise, verifiable). Helps a fresh agent estimate
context budget.
4. examples/kp-external-assessment.kpack/claims.md — three confidence
values rebalanced for credibility:
- C006 (0.87 → 0.72): "Numeric confidence floats are treated as a
weak point... calibration research suggests linguistic markers
more reliable" — confidence reduced to reflect that the underlying
calibration research is itself contested and the assessment treats
the redesign as a candidate, not a recommendation.
- C007 (0.88 → 0.78): "audience and deployment target unresolved" —
small reduction; the observation is durable but framed as
ongoing.
- C009 (0.84 → 0.68): "voice-surface idea remains one of KP:1's most
interesting open bets... not yet validated" — confidence reduced
to match the stated provisional posture.
Confidence histogram now spans 0.68-0.93 (was 0.84-0.93). The
tighter cluster invited the "Confidence Hallucination" critique
from the deep audit; the new spread reflects honest contestability
variation across the assessment's claims.
Items verified and confirmed correct (no fix needed):
5. JSON Schema voice-conditional structure (kp-pack.schema.json:342-348)
— the deep audit flagged the if/then placement as "non-canonical"
and worried it might not fire. Verified with four test fixtures:
voice+duration+pace passes; voice without duration is correctly
rejected; voice without pace is correctly rejected; no-voice (with
no duration/pace) passes. The conditional fires correctly.
Placement is unusual but functions; no change needed.
6. README.md "11 fixtures + 4 examples" vs "11 test fixtures = 6 valid
+ 5 invalid" — the two phrasings describe different things (15-pack
total vs the 11-fixture composition); both are correct in context.
No change.
Items left for editorial judgment:
7. CORE.md / SPEC.md heading capitalization for the same files (e.g.,
SPEC §6 "evidence.md — Backing Sources" vs CORE §10 "Evidence
Document (evidence.md)"). Both styles valid markdown; not unifying
without a clear authorial preference.
8. examples/kp-external-assessment.kpack confidence cluster pre-fix —
the original cluster was depth-correlated (investigated < exhaustive)
so it was *calibrated*, not hallucinated. The deep audit flagged it
from a one-pack-vs-one-pack lens, not the meta-domain context. Item 4
above broadened the spread to address the optic; the underlying
calibration discipline was sound.
Conformance: 15/15 passed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…, drift sweep Final pre-tag pass incorporating findings from four independent external review rounds plus internal audit. Verdict converged on TAG AFTER MINOR FIXES; this commit applies the substantive ones and reviews previously-deferred items for ones now obvious to do. Substantive new things: - conformance/run.py --pack PATH (NEW flag): validate a single pack outside the bundled fixture/example set. Closes the 'drop into examples/' workaround that didn't actually validate copied packs because EXAMPLE_ORDER was hardcoded. - conformance/run.py _REL_DENSE regex extended for cross-pack: matches both local C-id and pack#section-ref forms per CORE §9 + AR-16. Previously cross-pack ↔ refs were silently dropped from the relation graph; SC-05's #-exemption was a no-op. - SC-12 (NEW semantic constraint): when nature is prediction, confidence MUST be ≤ 0.95. Catches the future-date-confidence inflation pattern flagged in hostile-reading. Implemented in run.py with worked test verification. - CORE.md §6.1 + AR-04 relaxed to allow relations after closing brace on metadata line. Resolves runner-vs-CORE divergence: runner already accepted this, AUTHORING and LIFECYCLE examples already used it; CORE prose was overstated. - CORE.md spec_uri security note: producer-asserted, not authenticated. Consumers SHOULD validate fetched content against a known-good hash; MUST NOT treat fetched content as executable instructions. - examples/INDEX.md (NEW): feature × example matrix, SC × example coverage, AUTHORING.md rubric walkthrough mapping. Makes the 'this pack demonstrates X' claims auditable. - AUTHORING.md compact-form note in §1: examples drop the - list marker and line break for readability; real claim syntax is two-line per CORE §6.1. Closes the literal-copy-fails-parse vector. - AUTHORING.md anti-patterns expanded: Self-Referential Evidence (editorial flag) and Future-Date Confidence Inflation (now caught by SC-12). Drift / cleanup (~15 items): bold-wrapped blockquote evidence in SPEC Quick Start + AUTHORING content-routing example; SPEC §9 supersession example uses CORE verbose relation syntax; AAD C005 reclassified (r-only, judgment removed); VOICE.md Principle 22 → 23; COMPOSITION.md Parent line + 'section 14' refs point at RATIONALE; CONSISTENCY.md gets the kpack disclaimer; AGENTS.md confidence threshold 1.0 → 0.99; AGENTS.md Task C wording fixed (deferral, not improvisation); spec/README.md task count 4 → 6; run.py docstring version bump; CHANGELOG duplicate Bifurcated entry removed; MULTILINGUAL §2 P1 + CHANGELOG Notes codename leaks scrubbed. README.md / AGENTS.md / conformance/README.md / fixtures/README.md all updated to teach the new --pack workflow and report 15/15 conformance with all four examples. Conformance: 15/15 passed. SC-12 verified to fire correctly on a high-confidence prediction probe. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…Makefile + doc polish
Final sweep on items previously deferred. All landed without breaking the
existing 13 v0.8.0-preview tests; suite now 19/19.
New negative fixtures (one per substantive SC the runner enforces):
- cyclic-supersession.kpack → SC-04 (DAG violation)
- dangling-relation-target.kpack → SC-05 (intra-pack target missing)
- wrong-pack-name.kpack → SC-07 (Rosetta vs PACK.yaml identity)
- prediction-too-confident.kpack → SC-12 (confidence > 0.95 on prediction)
Tooling:
- Makefile (convenience wrapper for run.py): install / conformance / pack
PACK=path / lint / clean. Not a build system; the runner remains the
only validator.
- All count references swept from 15/15 → 19/19 and "11 fixtures"
→ "15 fixtures" across README.md, AGENTS.md, examples/{README,INDEX}.md,
conformance/{README,fixtures/README,grammar/README}.md, CORE.md, run.py
docstring. SC range labels likewise SC-01..SC-11 → SC-01..SC-12 where
the range form was used.
Documentation:
- CORE.md: top-of-file author hint pointing at AUTHORING.md; §3
decoration-fields paragraph documenting linguistic_epoch / ontology
deprecation alongside composition / files; §11 view-laundering
softened from MUST to SHOULD with editorial-discipline framing
(mechanical detection isn't possible; rule is producer-facing).
- PLAYBACK.md §9: new "Stable for v0.8.0-preview" subsection enumerating
the parts of the schema that will not change without a deprecation
cycle (top-level shape, AudienceProfile, four primary registers, P1
and P2 architectural rules, min_tier mechanism). The mutable-before-
v0.9 list is preserved as a sibling.
- RECONCILIATION.md: new "What to do today (v0.8.0-preview)" section
with a worked report example showing how to surface cross-pack
disagreement using existing primitives (annotate, surface, defer to
human; do NOT auto-flatten).
- RATIONALE.md §4: schema.org / JSON-LD knowledge graphs row added to
the Relationship to Existing Standards table — addresses "why not
schema.org?" with three concrete differences and notes the two
approaches compose via MAPPING.md.
- AGENTS.md: Task E secondary column now references LIFECYCLE.md §6
(supersession cascade) for the meeting-pack-vs-superseded-claim case.
Conformance: 19/19 (was 15/15; +4 negative fixtures).
No core schema changes; pre-v0.8.0-preview packs continue to validate.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Last consistency pass before tagging surfaced 9 cosmetic nits + one GH Action floating tag below latest. None substantive; conformance still 19/19. Doc fixes: - CHANGELOG.md broken relative links: stripped redundant `spec/` prefix from sibling-document links inside spec/CHANGELOG.md so they don't resolve to spec/spec/RATIONALE.md etc. Also fixed a §15/§17 Style Systems typo. - CORE.md SC table reordered: SC-12 was between SC-04 and SC-05; moved to the end after SC-11. - CHANGELOG.md "all 19 spec/*.md files" → "all 22 spec/*.md files" (matches actual count + AGENTS.md). - examples/README.md: pip install command pointed at a nonexistent ../conformance/requirements.txt; corrected to ../requirements.txt. - examples/INDEX.md --pack example: corrected path to examples/solar-energy-market.kpack so it works from repo root. - examples/INDEX.md + examples/README.md: solar-energy-market was described as "all four claim types," "all relation types," and "multiple views (display + voice)." Actual surface is o/r/i (no c), three relation symbols, and a single overview view. Matrix and prose now describe the actual surface honestly. - conformance/fixtures/README.md: SC-07 prose called pack: a "Rosetta header" field. Per CORE.md §3 the Rosetta header is the <!-- KP:1 ... --> comment; pack: lives in the YAML frontmatter. Tightened terminology with a parenthetical distinction. - conformance/fixtures/README.md: said the runner parses against the PEG. Aligned with conformance/README.md's "regex equivalent" framing. Behavior fix: - conformance/run.py --pack with no path silently fell through to the full-suite branch and exited green. Now prints `usage: run.py --pack PATH` and exits 2. Tooling bump: - .github/workflows/ci.yml: actions/setup-node@v6.3.0 → @v6.4.0 (SHA pin updated). Other pinned Actions (checkout v6.0.2, setup-python v6.2.0) confirmed already on latest tag. pyyaml>=6.0.3, jsonschema>=4.26, and markdownlint-cli@0.48.0 confirmed at latest PyPI/npm versions; no bump needed. Conformance: 19/19. No core schema changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Lines 349 to 351 in 827e0fb
Enforce SC-12 for verbose claim metadata
SC-12 is only applied in the dense metadata branch, but verbose claims can also declare nature: prediction (see CORE §6.2). In this branch you record confidence and evidence but never inspect nature, so a verbose claim like confidence: 0.99 | ... | nature: prediction will incorrectly pass validation. That creates a syntax-dependent bypass for a new semantic constraint and lets invalid packs pass conformance.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # found in some maximal-fixture refs while preferring the | ||
| # AR-16 lowercase-hyphen convention). Section ref is freeform until | ||
| # the next delimiter (whitespace or comma) per CORE \u00a79. | ||
| r"(C\d+(?:-v\d+)?|[a-z][a-z0-9.-]*#[^\s,]+)" |
There was a problem hiding this comment.
The new dense relation regex accepts pack names with dots ([a-z][a-z0-9.-]*), but CORE’s cross-pack format requires pack_name to match [a-z0-9-]+. This means malformed references such as ↔foo.bar#section are treated as valid targets and then exempted by SC-05, so invalid relation syntax can slip through validation.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Releases KP:1 v0.8.0-preview by restructuring the spec into explicit normative “lanes”, adding new companion documents (AUTHORING, RATIONALE, PLAYBACK, RECONCILIATION, EXTENSIONS), and expanding conformance coverage (runner + fixtures + examples).
Changes:
- Reframes the specification architecture (CORE vs SPEC vs topic-authoritative companions) and updates companion docs accordingly.
- Adds/updates conformance tooling and fixtures (SC-12,
--packflag, additional invalid fixtures, new validated example packs). - Improves AI-first onboarding/discoverability (AGENTS.md,
spec_uri/spec_version, referencekpackcontract-pointer stub).
Reviewed changes
Copilot reviewed 62 out of 62 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| spec/VOICE.md | Adds planned-tooling disclaimer and introduces register voice metadata axis; updates rationale cross-links. |
| spec/STORAGE.md | Updates lifecycle rationale cross-reference to RATIONALE principles. |
| spec/RECONCILIATION.md | Adds new stub companion defining current (v0.8) guidance for cross-pack contradictions. |
| spec/README.md | Documents the “three normative lanes” model and expands companion index. |
| spec/RATIONALE.md | Adds new informative rationale companion (principles, style systems, positioning, standards comparison). |
| spec/PLAYBACK.md | Adds new experimental companion specifying playback planning/session contracts. |
| spec/ORGANIZATION.md | Updates repository/spec layout examples to include new/updated spec files. |
| spec/NOTES.md | Removes stale parent pointer metadata. |
| spec/MULTILINGUAL.md | Adds planned-tooling disclaimer; adds en-GB guidance, register sub-distinctions, and a normative evidentiary multilingual exception. |
| spec/MAPPING.md | Marks mapping document as informative draft (non-normative). |
| spec/LIFECYCLE.md | Adds planned-tooling disclaimer; adds supersession cascade section; updates examples and rationale references. |
| spec/EXTENSIONS.md | Adds new extensions catalogue companion documenting common extensions.* shapes. |
| spec/DEFINITIONS.md | Updates parent pointer; adds cross-links to EXTENSIONS for entity/relation instances; updates rationale references. |
| spec/CORE.md | Updates release metadata; expands scope/cross-links; adds spec_uri/spec_version manifest fields; updates relation-on-metadata-line rules and SC-12 text. |
| spec/CONVENTIONS.md | Removes stale parent pointer metadata. |
| spec/CONSISTENCY.md | Adds planned-tooling disclaimer; updates rationale references. |
| spec/COMPOSITION.md | Updates parent pointer and examples (symbol glyphs, claim IDs); adds planned-tooling disclaimer; updates rationale references. |
| spec/CHANGELOG.md | Adds v0.8.0-preview release entry with detailed change log. |
| spec/BUNDLE.md | Adds planned-tooling disclaimer; removes stale parent pointer metadata. |
| spec/AUTHORING.md | Adds new informative companion with producer-side decision rubrics and anti-patterns. |
| spec/ARCHIVE.md | Adds planned-tooling disclaimer and a “format discoverability” section aligned with spec_uri/spec_version. |
| reference/README.md | Reframes reference tooling as stub/contract-pointer and documents what exists today. |
| reference/kpack | Adds a kpack CLI stub that maps subcommands to spec sections. |
| README.md | Updates repo overview for v0.8.0-preview; expands examples/conformance instructions. |
| Makefile | Adds convenience targets for running conformance and validating a single pack. |
| examples/README.md | Updates examples listing, guidance, and validation instructions for 4 examples. |
| examples/kp-external-assessment.kpack/claims.md | Adjusts confidence values and adds explanatory prose for calibration. |
| examples/INDEX.md | Adds new index mapping examples to features, SC/AR coverage, and AUTHORING rubrics. |
| examples/auction-house-consignment-review.kpack/PACK.yaml | Adds new example pack manifest (incl. spec_uri/spec_version) and views. |
| examples/auction-house-consignment-review.kpack/claims.md | Adds new example pack claims demonstrating contradiction handling, cross-pack ↔, and decision framing. |
| examples/auction-house-consignment-review.kpack/evidence.md | Adds evidence records for the new auction-house example pack. |
| examples/auction-house-consignment-review.kpack/views/decision.md | Adds committee-facing decision view for the new example pack. |
| examples/auction-house-consignment-review.kpack/views/specialist.md | Adds specialist working-notes view for the new example pack. |
| examples/auction-house-consignment-review.kpack/views/consignor-letter.md | Adds formal consignor-letter view for the new example pack. |
| examples/auction-house-consignment-review.kpack/views/voice/briefing.md | Adds voice briefing view (with register) for the new example pack. |
| examples/art-acquisition-decision.kpack/PACK.yaml | Adds new art acquisition example pack manifest (incl. spec_uri/spec_version) and views. |
| examples/art-acquisition-decision.kpack/claims.md | Adds new example pack claims exercising supersession, contradiction qualifiers, and prediction constraints. |
| examples/art-acquisition-decision.kpack/evidence.md | Adds evidence records for the new art acquisition example pack. |
| examples/art-acquisition-decision.kpack/views/overview.md | Adds buyer-facing overview view for the new example pack. |
| examples/art-acquisition-decision.kpack/views/counsel.md | Adds counsel-facing audit/risk view for the new example pack. |
| examples/art-acquisition-decision.kpack/views/voice/briefing.md | Adds voice briefing view (with register) for the new example pack. |
| conformance/run.py | Extends runner with new invalid fixtures, cross-pack ↔ parsing, SC-12 enforcement (partial), and --pack validation mode. |
| conformance/README.md | Updates fixture counts and runner contract wording for 19/19. |
| conformance/grammar/README.md | Updates SC range references to include SC-12. |
| conformance/grammar/kp-pack.schema.json | Adds spec_uri/spec_version, updates display constraints, and adds co-author role. |
| conformance/fixtures/README.md | Updates fixture documentation for 19/19 and documents new invalid fixtures. |
| conformance/fixtures/invalid/wrong-pack-name.kpack/PACK.yaml | Adds new invalid fixture for SC-07 (PACK.yaml). |
| conformance/fixtures/invalid/wrong-pack-name.kpack/evidence.md | Adds evidence for SC-07 invalid fixture. |
| conformance/fixtures/invalid/wrong-pack-name.kpack/claims.md | Adds claims for SC-07 invalid fixture (frontmatter mismatch). |
| conformance/fixtures/invalid/prediction-too-confident.kpack/PACK.yaml | Adds new invalid fixture for SC-12 (PACK.yaml). |
| conformance/fixtures/invalid/prediction-too-confident.kpack/evidence.md | Adds evidence for SC-12 invalid fixture. |
| conformance/fixtures/invalid/prediction-too-confident.kpack/claims.md | Adds claims for SC-12 invalid fixture (prediction confidence cap). |
| conformance/fixtures/invalid/dangling-relation-target.kpack/PACK.yaml | Adds new invalid fixture for SC-05 (PACK.yaml). |
| conformance/fixtures/invalid/dangling-relation-target.kpack/evidence.md | Adds evidence for SC-05 invalid fixture. |
| conformance/fixtures/invalid/dangling-relation-target.kpack/claims.md | Adds claims for SC-05 invalid fixture (dangling target). |
| conformance/fixtures/invalid/cyclic-supersession.kpack/PACK.yaml | Adds new invalid fixture for SC-04 (PACK.yaml). |
| conformance/fixtures/invalid/cyclic-supersession.kpack/evidence.md | Adds evidence for SC-04 invalid fixture. |
| conformance/fixtures/invalid/cyclic-supersession.kpack/claims.md | Adds claims for SC-04 invalid fixture (supersession cycle). |
| CITATION.cff | Updates citation metadata to v0.8.0-preview and expands abstract/keywords. |
| AGENTS.md | Adds AI-first task routing/reading map and MUST-NOT guidance. |
| .github/workflows/ci.yml | Updates pinned actions/setup-node SHA to v6.4.0. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| except ValueError: | ||
| errs.append(Err("parse", f"invalid confidence '{conf_s}' for {cid}")) | ||
|
|
||
| # Position 5 (index 5) is nature when present (judgment | prediction | meta) |
Comment on lines
+28
to
+33
| "lint": ( | ||
| "spec/SPEC.md §13 Tooling", | ||
| "Validate a pack's structure, references, and semantic constraints. " | ||
| "Today, run `python3 conformance/run.py` after copying your pack into " | ||
| "examples/, or import `validate_pack` from conformance/run.py.", | ||
| ), |
Comment on lines
84
to
90
| | Field | Required | Values | Purpose | | ||
| |-------|----------|--------|---------| | ||
| | `voice` | Yes | View identifier | Matches the `name` field in PACK.yaml voice view declaration | | ||
| | `duration` | Yes | `~N seconds` or `~N minutes` | Approximate spoken duration at natural pace | | ||
| | `pace` | Yes | `brisk`, `measured`, `deliberate` | Speaking tempo hint for TTS or human reader | | ||
| | `register` | Recommended | `plain`, `curatorial`, `technical`, `investor` | Voice register — diction and emphasis profile (see §4.1 below) | | ||
| | `generated` | Recommended | ISO date + claims version | Staleness detection (same mechanism as display views) | |
Comment on lines
323
to
+330
| errs.append(Err("parse", f"invalid confidence '{conf_s}' for {cid}")) | ||
|
|
||
| # Position 5 (index 5) is nature when present (judgment | prediction | meta) | ||
| if conf_val is not None and len(parts) >= 6: | ||
| nature_s = parts[5].strip() | ||
| if nature_s == "prediction" and conf_val > 0.95: | ||
| predictions_high_conf.append((cid, conf_val)) | ||
|
|
Comment on lines
+142
to
+151
| _REL_DENSE = re.compile( | ||
| r"(\u2297~|\u2297!|\u2297|\u2192|\u2190|\u2298|\u2194|~)" | ||
| # Target: either a local claim ID (C\d+(?:-v\d+)?) or a cross-pack | ||
| # reference of the form pack_name#section_ref per CORE \u00a79 / AR-16. | ||
| # Pack name follows [a-z][a-z0-9.-]* (allows .kpack-style suffixes | ||
| # found in some maximal-fixture refs while preferring the | ||
| # AR-16 lowercase-hyphen convention). Section ref is freeform until | ||
| # the next delimiter (whitespace or comma) per CORE \u00a79. | ||
| r"(C\d+(?:-v\d+)?|[a-z][a-z0-9.-]*#[^\s,]+)" | ||
| ) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Public Draft of
KP:1advances fromv0.7-preview→v0.8.0-preview. Major themes:spec/README.md— CORE.md (implementer surface), SPEC.md (full normative + rationale + ecosystem), and topic-authoritative companions.AGENTS.mdtask-routing file plusspec/AUTHORING.mdproducer-side decision rubrics.spec/RATIONALE.md(NEW companion, informative) houses Design Principles, Style Systems rationale, and Relationship to Existing Standards table previously interleaved into SPEC.md normative prose.RECONCILIATION.md(stub for cross-pack consolidation, deferred to v0.9/v1.0), enrichedEXTENSIONS.md,LIFECYCLE.md§6 supersession cascade.art-acquisition-decision.kpack(buyer-side, full feature surface, walks AUTHORING.md rubrics end-to-end) andauction-house-consignment-review.kpack(consigner-side decline path with cross-pack↔references).natureisprediction, confidence MUST be ≤ 0.95.--pack PATHflag for arbitrary single-pack validation;Makefileconvenience wrapper; cross-pack reference parsing in the runner.spec_uriandspec_versionoptional manifest fields let a sealed.kpackarchive self-describe to a cold receiver.Full surface in
spec/CHANGELOG.md.Compatibility
spec_uri,spec_version,extensions.translations, voiceregisteraxis) are all optional or recommended.Test plan
python3 conformance/run.pyreports19/19 passedPost-merge
After this PR merges:
v0.8.0-previewonmain🤖 Generated with Claude Code