From 61b711a328bdc9648d4622e541721732a29f9f1f Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Feb 2026 02:11:20 +0000 Subject: [PATCH] Expose ODD definition in navigation, indexing, and metadata MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The primary ODD definition (odd/README.md) was tier 0, making it invisible to all compiled packs via FR-2 exclusion. Agents consuming packs could not find what "ODD" means. Multiple entry points also lacked searchable metadata. Key fixes: - odd/README.md: tier 0→1, title now "What is ODD?", added definition/ methodology/philosophy tags - odd/terminology.md: added "ODD (Outcomes-Driven Development)" as the first core term — previously defined every term except ODD itself - docs/oddkit/ABOUT.md: added full frontmatter (had none — invisible to all indexing) - docs/oddkit/SYSTEM-MAP.md: added ODD acronym expansion and tags - odd/index.md: added subtitle, definition/methodology tags - odd/manifesto.md: added outcomes-driven-development/definition tags - odd/orientation-map.md: added outcomes-driven-development tag Rebuilt docs index and synced content. https://claude.ai/code/session_01GnDQtvovXdJotMSSVZyBRT --- docs/oddkit/ABOUT.md | 11 + docs/oddkit/SYSTEM-MAP.md | 6 +- odd/README.md | 6 +- odd/index.md | 5 +- odd/manifesto.md | 2 +- odd/orientation-map.md | 2 +- odd/terminology.md | 16 +- public/_compiled/index/docs.json | 979 ++++++++++++------ public/content/canon/CHANGELOG.md | 41 + .../canon/epistemic-surface-extraction.md | 221 ++++ public/content/canon/meta/pack.json | 4 +- .../canon/verification-and-evidence.md | 1 + public/content/manifest.json | 91 +- public/content/odd/README.md | 6 +- public/content/odd/index.md | 5 +- public/content/odd/manifesto.md | 2 +- public/content/odd/orientation-map.md | 2 +- public/content/odd/terminology.md | 16 +- 18 files changed, 1036 insertions(+), 380 deletions(-) create mode 100644 public/content/canon/epistemic-surface-extraction.md diff --git a/docs/oddkit/ABOUT.md b/docs/oddkit/ABOUT.md index b15d0577..eeaf7eac 100644 --- a/docs/oddkit/ABOUT.md +++ b/docs/oddkit/ABOUT.md @@ -1,3 +1,14 @@ +--- +uri: oddkit://about +title: "About oddkit" +audience: docs +exposure: nav +tier: 1 +voice: neutral +stability: stable +tags: ["oddkit", "odd", "definition", "outcomes-driven-development", "what-is-odd", "about", "orientation"] +--- + # About oddkit > **ODD** = **Outcomes-Driven Development** — see [/odd/README.md](/odd/README.md) for the full philosophy. diff --git a/docs/oddkit/SYSTEM-MAP.md b/docs/oddkit/SYSTEM-MAP.md index 7e7abed2..95176b3b 100644 --- a/docs/oddkit/SYSTEM-MAP.md +++ b/docs/oddkit/SYSTEM-MAP.md @@ -6,14 +6,16 @@ exposure: nav tier: 2 voice: neutral stability: stable -tags: ["oddkit", "orchestrator", "librarian", "validation", "arbitration"] +tags: ["oddkit", "odd", "outcomes-driven-development", "orchestrator", "librarian", "validation", "arbitration"] --- # Oddkit System Map > A practical guide for understanding oddkit behavior, outcomes, and next actions. -This document explains **what oddkit does**, **how to interpret its outputs**, and **what actions are expected next**. +**ODD** = **Outcomes-Driven Development** — an approach to building software that prioritizes real-world results over artifacts. See [/odd/README.md](/odd/README.md) for the full philosophy. + +This document explains **what oddkit does**, **how to interpret its outputs**, and **what actions are expected next**. It is not a design doc, tutorial, or philosophy statement. --- diff --git a/odd/README.md b/odd/README.md index ae526051..d856e79a 100644 --- a/odd/README.md +++ b/odd/README.md @@ -1,12 +1,12 @@ --- uri: klappy://public/odd -title: "ODD Manifesto — Public" +title: "What is ODD? — Outcomes-Driven Development" audience: public exposure: nav -tier: 0 +tier: 1 voice: neutral stability: semi_stable -tags: ["odd", "public", "overview"] +tags: ["odd", "definition", "outcomes-driven-development", "what-is-odd", "methodology", "philosophy", "public", "overview"] relevance: routing execution_posture: routing assets: {"practice_video":"/assets/odd/odd-in-practice.mp4","misconception_image":"/assets/odd/odd-is-not-a-framework.png","deep_dive_audio":"/assets/odd/why-evidence-beats-confidence.m4a"} diff --git a/odd/index.md b/odd/index.md index 690f82f8..f4306096 100644 --- a/odd/index.md +++ b/odd/index.md @@ -1,12 +1,13 @@ --- uri: klappy://odd -title: "Outcomes-Driven Development" +title: "Outcomes-Driven Development (ODD)" +subtitle: "ODD = Outcomes-Driven Development — the philosophical and operational foundation for this repository." audience: canon exposure: nav tier: 1 voice: neutral stability: stable -tags: ["odd", "index"] +tags: ["odd", "index", "definition", "outcomes-driven-development", "what-is-odd", "methodology"] relevance: routing execution_posture: routing --- diff --git a/odd/manifesto.md b/odd/manifesto.md index b82c8fd3..01caccf3 100644 --- a/odd/manifesto.md +++ b/odd/manifesto.md @@ -6,7 +6,7 @@ exposure: nav tier: 2 voice: neutral stability: stable -tags: ["odd", "philosophy"] +tags: ["odd", "philosophy", "outcomes-driven-development", "manifesto", "governance", "definition"] relevance: background execution_posture: exploratory --- diff --git a/odd/orientation-map.md b/odd/orientation-map.md index bd66adb8..9a542ac7 100644 --- a/odd/orientation-map.md +++ b/odd/orientation-map.md @@ -6,7 +6,7 @@ exposure: nav tier: 3 voice: neutral stability: semi_stable -tags: ["odd", "orientation", "mental-model"] +tags: ["odd", "orientation", "mental-model", "outcomes-driven-development", "hierarchy"] relevance: supporting execution_posture: operational --- diff --git a/odd/terminology.md b/odd/terminology.md index 22a1a9c0..893bb14f 100644 --- a/odd/terminology.md +++ b/odd/terminology.md @@ -8,7 +8,7 @@ exposure: nav tier: 1 voice: neutral stability: evolving -tags: ["odd", "terminology", "disambiguation", "boundary"] +tags: ["odd", "terminology", "disambiguation", "boundary", "definition", "outcomes-driven-development", "glossary"] relevance: supporting execution_posture: operational --- @@ -57,6 +57,20 @@ If terminology lived under `canon/`, language would appear post hoc. ODD would l ## Core Terms +### ODD (Outcomes-Driven Development) + +**ODD meaning:** Outcomes-Driven Development — an approach to building software that prioritizes real-world results over artifacts. In an AI-accelerated environment, the limiting factor is no longer production speed; it is clarity of intent, quality of verification, and the ability to choose among outcomes. ODD makes those constraints explicit. + +**Not:** A framework, a fixed workflow, or a claim that outcomes can be fully predicted. + +**Core thesis:** The primary job of development is not writing code. It is defining outcomes, enforcing constraints, and verifying reality. AI accelerates execution; governance preserves trust. + +**Test:** Are decisions governed by verifiable outcomes, or by artifacts and activity? + +**See:** [/odd/README.md](/odd/README.md) for the public introduction, [/odd/manifesto.md](/odd/manifesto.md) for the extended operational framework. + +--- + ### Outcome **ODD meaning:** A verifiable state of reality that can be demonstrated, not just described. diff --git a/public/_compiled/index/docs.json b/public/_compiled/index/docs.json index 5fc3214a..1cab4c82 100644 --- a/public/_compiled/index/docs.json +++ b/public/_compiled/index/docs.json @@ -1,6 +1,6 @@ { "version": "1.1", - "generated_at": "2026-02-01T00:28:47.013Z", + "generated_at": "2026-02-06T02:10:21.952Z", "description": "Fast-lookup index for Librarian retrieval. Per docs/agents/librarian/contract.md", "schema_notes": { "authority_band": "Resolved authority (frontmatter override > inferred from root)", @@ -30,20 +30,20 @@ } }, "stats": { - "total_documents": 184, - "with_frontmatter": 176, - "with_headings": 180, + "total_documents": 186, + "with_frontmatter": 179, + "with_headings": 182, "by_root": { "apocrypha": 14, - "canon": 48, - "docs": 90, + "canon": 49, + "docs": 91, "interfaces": 6, "odd": 26 }, "by_authority": { "non-governing": 14, - "governing": 74, - "operational": 96 + "governing": 75, + "operational": 97 }, "with_authority_override": 0, "with_authority_warning": 0 @@ -233,8 +233,8 @@ "authority_band": "non-governing", "authority_inferred": "non-governing", "uri": "klappy://apocrypha/artifacts/surface-extraction", - "title": "Epistemic Surface Extraction", - "subtitle": "Draft rules for making visual/audio/video artifacts *legible* to agents without turning them into doctrine.", + "title": "Epistemic Surface Extraction (PROMOTED)", + "subtitle": "**⚠️ PROMOTED**: This document has been promoted to Canon. See [/canon/epistemic-surface-extraction.md](/canon/epistemic-surface-extraction.md) for the authoritative version.", "tags": [ "apocrypha", "artifacts", @@ -242,9 +242,10 @@ "surface", "ocr", "asr", - "video" + "video", + "promoted" ], - "stability": "evolving", + "stability": "archived", "tier": "2", "audience": "apocrypha", "exposure": "hidden", @@ -260,77 +261,77 @@ { "level": 2, "text": "Purpose", - "line": 6 + "line": 10 }, { "level": 2, "text": "Outputs (Sidecar Convention)", - "line": 22 + "line": 26 }, { "level": 2, "text": "Invariant Contract (All Modalities)", - "line": 33 + "line": 37 }, { "level": 2, "text": "Segmentation Rules by Modality", - "line": 58 + "line": 62 }, { "level": 3, "text": "Slides / PDFs", - "line": 60 + "line": 64 }, { "level": 3, "text": "Images (single)", - "line": 65 + "line": 69 }, { "level": 3, "text": "Audio", - "line": 70 + "line": 74 }, { "level": 3, "text": "Video", - "line": 86 + "line": 90 }, { "level": 2, "text": "Anchor Contract (Audio + Video)", - "line": 97 + "line": 101 }, { "level": 3, "text": "snippet_hash", - "line": 115 + "line": 119 }, { "level": 2, "text": "Surface Bullet Rules", - "line": 128 + "line": 132 }, { "level": 2, "text": "Cross-Reference Relations", - "line": 139 + "line": 143 }, { "level": 2, "text": "Containment (Mandatory)", - "line": 153 + "line": 157 }, { "level": 2, "text": "Promotion Rule (Simple)", - "line": 165 + "line": 169 }, { "level": 2, "text": "Status", - "line": 175 + "line": 179 } ], "heading_count": 16, @@ -1651,7 +1652,7 @@ }, { "level": 2, - "text": "0.27.0 — 2026-01-31", + "text": "0.28.0 — 2026-02-05", "line": 9 }, { @@ -1659,1123 +1660,1148 @@ "text": "Added", "line": 15 }, + { + "level": 3, + "text": "Changed", + "line": 21 + }, { "level": 3, "text": "Philosophy", - "line": 29 + "line": 34 + }, + { + "level": 3, + "text": "Notes", + "line": 42 + }, + { + "level": 2, + "text": "0.27.0 — 2026-01-31", + "line": 50 + }, + { + "level": 3, + "text": "Added", + "line": 56 + }, + { + "level": 3, + "text": "Philosophy", + "line": 70 }, { "level": 3, "text": "Relationship", - "line": 39 + "line": 80 }, { "level": 3, "text": "Notes", - "line": 47 + "line": 88 }, { "level": 2, "text": "0.26.0 — 2026-01-31", - "line": 54 + "line": 95 }, { "level": 3, "text": "Added", - "line": 60 + "line": 101 }, { "level": 3, "text": "Philosophy", - "line": 74 + "line": 115 }, { "level": 3, "text": "Architecture Decision", - "line": 84 + "line": 125 }, { "level": 3, "text": "Notes", - "line": 90 + "line": 131 }, { "level": 2, "text": "0.25.0 — 2026-01-31", - "line": 98 + "line": 139 }, { "level": 3, "text": "Added", - "line": 104 + "line": 145 }, { "level": 3, "text": "Changed", - "line": 128 + "line": 169 }, { "level": 3, "text": "Philosophy", - "line": 132 + "line": 173 }, { "level": 3, "text": "Epoch Lock", - "line": 142 + "line": 183 }, { "level": 2, "text": "0.24.0 — 2026-01-30", - "line": 148 + "line": 189 }, { "level": 3, "text": "Added", - "line": 154 + "line": 195 }, { "level": 3, "text": "Changed", - "line": 160 + "line": 201 }, { "level": 3, "text": "Philosophy", - "line": 166 + "line": 207 }, { "level": 3, "text": "Notes", - "line": 174 + "line": 215 }, { "level": 2, "text": "0.23.0 — 2026-01-29", - "line": 182 + "line": 223 }, { "level": 3, "text": "Added", - "line": 188 + "line": 229 }, { "level": 3, "text": "Updated", - "line": 198 + "line": 239 }, { "level": 3, "text": "Philosophy", - "line": 206 + "line": 247 }, { "level": 3, "text": "Agent Interaction Flow", - "line": 213 + "line": 254 }, { "level": 2, "text": "0.22.0 — 2026-01-29", - "line": 223 + "line": 264 }, { "level": 3, "text": "Added", - "line": 229 + "line": 270 }, { "level": 3, "text": "Philosophy", - "line": 243 + "line": 284 }, { "level": 3, "text": "Initial Registrations", - "line": 250 + "line": 291 }, { "level": 2, "text": "0.21.0 — 2026-01-29", - "line": 257 + "line": 298 }, { "level": 3, "text": "Added", - "line": 263 + "line": 304 }, { "level": 3, "text": "Philosophy", - "line": 269 + "line": 310 }, { "level": 3, "text": "Integration", - "line": 276 + "line": 317 }, { "level": 3, "text": "Ledger Schemas", - "line": 282 + "line": 323 }, { "level": 2, "text": "0.20.1 — 2026-01-29", - "line": 290 + "line": 331 }, { "level": 3, "text": "Added", - "line": 296 + "line": 337 }, { "level": 3, "text": "Philosophy", - "line": 300 + "line": 341 }, { "level": 2, "text": "0.20.0 — 2026-01-29", - "line": 308 + "line": 349 }, { "level": 3, "text": "Added", - "line": 314 + "line": 355 }, { "level": 3, "text": "Philosophy", - "line": 326 + "line": 367 }, { "level": 3, "text": "Relationship to Other Canon", - "line": 333 + "line": 374 }, { "level": 3, "text": "Notes", - "line": 339 + "line": 380 }, { "level": 2, "text": "0.19.0 — 2026-01-29", - "line": 347 + "line": 388 }, { "level": 3, "text": "Added", - "line": 353 + "line": 394 }, { "level": 3, "text": "Philosophy", - "line": 357 + "line": 398 }, { "level": 3, "text": "Hard Constraints Codified", - "line": 364 + "line": 405 }, { "level": 3, "text": "Valid Arbitration Outcomes", - "line": 371 + "line": 412 }, { "level": 3, "text": "Implementation Reference", - "line": 378 + "line": 419 }, { "level": 3, "text": "Notes", - "line": 388 + "line": 429 }, { "level": 2, "text": "0.18.0 — 2026-01-28", - "line": 396 + "line": 437 }, { "level": 3, "text": "Added", - "line": 402 + "line": 443 }, { "level": 3, "text": "Philosophy", - "line": 416 + "line": 457 }, { "level": 3, "text": "Structure", - "line": 423 + "line": 464 }, { "level": 3, "text": "Notes", - "line": 435 + "line": 476 }, { "level": 2, "text": "0.17.0 — 2026-01-26", - "line": 443 + "line": 484 }, { "level": 3, "text": "Added", - "line": 449 + "line": 490 }, { "level": 3, "text": "Philosophy", - "line": 457 + "line": 498 }, { "level": 3, "text": "Canonical Tie-In", - "line": 463 + "line": 504 }, { "level": 2, "text": "0.16.0 — 2026-01-26", - "line": 471 + "line": 512 }, { "level": 3, "text": "Added (Source Doctrine)", - "line": 483 + "line": 524 }, { "level": 3, "text": "Philosophy Introduced", - "line": 503 + "line": 544 }, { "level": 3, "text": "Usage (Initial Adoption)", - "line": 520 + "line": 561 }, { "level": 2, "text": "0.15.0 — 2026-01-23", - "line": 532 + "line": 573 }, { "level": 3, "text": "Added", - "line": 538 + "line": 579 }, { "level": 3, "text": "Changed", - "line": 542 + "line": 583 }, { "level": 3, "text": "Philosophy", - "line": 547 + "line": 588 }, { "level": 3, "text": "Origin", - "line": 553 + "line": 594 }, { "level": 2, "text": "0.14.0 — 2026-01-23", - "line": 565 + "line": 606 }, { "level": 3, "text": "Added", - "line": 571 + "line": 612 }, { "level": 3, "text": "Philosophy", - "line": 576 + "line": 617 }, { "level": 3, "text": "Notes", - "line": 582 + "line": 623 }, { "level": 2, "text": "0.13.0 — 2026-01-23", - "line": 589 + "line": 630 }, { "level": 3, "text": "Added", - "line": 595 + "line": 636 }, { "level": 3, "text": "Changed", - "line": 599 + "line": 640 }, { "level": 3, "text": "Added (Lane)", - "line": 603 + "line": 644 }, { "level": 3, "text": "Philosophy", - "line": 611 + "line": 652 }, { "level": 3, "text": "Root Cause Documented", - "line": 617 + "line": 658 }, { "level": 2, "text": "0.12.0 — 2026-01-22", - "line": 623 + "line": 664 }, { "level": 3, "text": "Changed", - "line": 629 + "line": 670 }, { "level": 3, "text": "Distribution After Reclassification", - "line": 637 + "line": 678 }, { "level": 3, "text": "Philosophy", - "line": 646 + "line": 687 }, { "level": 3, "text": "Invariants Held", - "line": 655 + "line": 696 }, { "level": 2, "text": "0.11.0 — 2026-01-22", - "line": 665 + "line": 706 }, { "level": 3, "text": "Added", - "line": 671 + "line": 712 }, { "level": 3, "text": "Changed", - "line": 678 + "line": 719 }, { "level": 3, "text": "Philosophy", - "line": 687 + "line": 728 }, { "level": 3, "text": "Invariant Locked", - "line": 693 + "line": 734 }, { "level": 2, "text": "0.10.0 — 2026-01-21", - "line": 701 + "line": 742 }, { "level": 3, "text": "Added", - "line": 707 + "line": 748 }, { "level": 3, "text": "Changed", - "line": 711 + "line": 752 }, { "level": 3, "text": "Philosophy", - "line": 719 + "line": 760 }, { "level": 3, "text": "Ontology Enforcement", - "line": 725 + "line": 766 }, { "level": 2, "text": "0.9.0 — 2026-01-21", - "line": 734 + "line": 775 }, { "level": 3, "text": "Added", - "line": 740 + "line": 781 }, { "level": 3, "text": "Changed", - "line": 750 + "line": 791 }, { "level": 3, "text": "Philosophy", - "line": 759 + "line": 800 }, { "level": 3, "text": "Canon Rule", - "line": 766 + "line": 807 }, { "level": 2, "text": "0.8.0 — 2026-01-21", - "line": 775 + "line": 816 }, { "level": 3, "text": "Added", - "line": 781 + "line": 822 }, { "level": 3, "text": "Changed", - "line": 798 + "line": 839 }, { "level": 3, "text": "Philosophy", - "line": 805 + "line": 846 }, { "level": 2, "text": "0.7.0 — 2026-01-21", - "line": 814 + "line": 855 }, { "level": 3, "text": "Added", - "line": 820 + "line": 861 }, { "level": 3, "text": "Changed", - "line": 831 + "line": 872 }, { "level": 3, "text": "Philosophy", - "line": 839 + "line": 880 }, { "level": 3, "text": "Notes", - "line": 846 + "line": 887 }, { "level": 2, "text": "0.6.1 — 2026-01-21", - "line": 854 + "line": 895 }, { "level": 3, "text": "Fixed", - "line": 860 + "line": 901 }, { "level": 3, "text": "Changed", - "line": 866 + "line": 907 }, { "level": 3, "text": "Added", - "line": 871 + "line": 912 }, { "level": 3, "text": "Philosophy", - "line": 879 + "line": 920 }, { "level": 2, "text": "0.6.0 — 2026-01-21", - "line": 888 + "line": 929 }, { "level": 3, "text": "Breaking Changes", - "line": 894 + "line": 935 }, { "level": 3, "text": "Added", - "line": 900 + "line": 941 }, { "level": 3, "text": "Changed", - "line": 906 + "line": 947 }, { "level": 3, "text": "Philosophy", - "line": 912 + "line": 953 }, { "level": 3, "text": "Migration Notes", - "line": 918 + "line": 959 }, { "level": 2, "text": "0.5.4 — 2026-01-21", - "line": 927 + "line": 968 }, { "level": 3, "text": "Added", - "line": 933 + "line": 974 }, { "level": 3, "text": "Changed", - "line": 940 + "line": 981 }, { "level": 3, "text": "Removed", - "line": 946 + "line": 987 }, { "level": 3, "text": "Philosophy", - "line": 951 + "line": 992 }, { "level": 3, "text": "Notes", - "line": 958 + "line": 999 }, { "level": 2, "text": "0.5.3 — 2026-01-21", - "line": 965 + "line": 1006 }, { "level": 3, "text": "Added", - "line": 971 + "line": 1012 }, { "level": 3, "text": "Changed", - "line": 975 + "line": 1016 }, { "level": 3, "text": "Philosophy", - "line": 983 + "line": 1024 }, { "level": 3, "text": "Notes", - "line": 990 + "line": 1031 }, { "level": 2, "text": "0.5.2 — 2026-01-20", - "line": 998 + "line": 1039 }, { "level": 3, "text": "Changed", - "line": 1004 + "line": 1045 }, { "level": 3, "text": "Added", - "line": 1022 + "line": 1063 }, { "level": 3, "text": "Philosophy", - "line": 1027 + "line": 1068 }, { "level": 3, "text": "Notes", - "line": 1033 + "line": 1074 }, { "level": 2, "text": "0.5.1 — 2026-01-20", - "line": 1040 + "line": 1081 }, { "level": 3, "text": "Added", - "line": 1046 + "line": 1087 }, { "level": 3, "text": "Changed", - "line": 1050 + "line": 1091 }, { "level": 3, "text": "Philosophy", - "line": 1055 + "line": 1096 }, { "level": 3, "text": "Notes", - "line": 1062 + "line": 1103 }, { "level": 2, "text": "0.5.0 — 2026-01-19", - "line": 1069 + "line": 1110 }, { "level": 3, "text": "Added", - "line": 1075 + "line": 1116 }, { "level": 3, "text": "Changed", - "line": 1081 + "line": 1122 }, { "level": 3, "text": "Breaking Changes (Epoch Transition)", - "line": 1086 + "line": 1127 }, { "level": 3, "text": "Philosophy", - "line": 1092 + "line": 1133 }, { "level": 3, "text": "Notes", - "line": 1098 + "line": 1139 }, { "level": 2, "text": "0.4.10 — 2026-01-19", - "line": 1105 + "line": 1146 }, { "level": 3, "text": "Added", - "line": 1111 + "line": 1152 }, { "level": 3, "text": "Changed", - "line": 1115 + "line": 1156 }, { "level": 3, "text": "Philosophy", - "line": 1119 + "line": 1160 }, { "level": 3, "text": "Notes", - "line": 1126 + "line": 1167 }, { "level": 2, "text": "0.4.9 — 2026-01-19", - "line": 1133 + "line": 1174 }, { "level": 3, "text": "Added", - "line": 1139 + "line": 1180 }, { "level": 3, "text": "Changed", - "line": 1144 + "line": 1185 }, { "level": 3, "text": "Philosophy", - "line": 1151 + "line": 1192 }, { "level": 3, "text": "Notes", - "line": 1158 + "line": 1199 }, { "level": 2, "text": "0.4.8 — 2026-01-19", - "line": 1165 + "line": 1206 }, { "level": 3, "text": "Added", - "line": 1171 + "line": 1212 }, { "level": 3, "text": "Changed", - "line": 1176 + "line": 1217 }, { "level": 3, "text": "Philosophy", - "line": 1185 + "line": 1226 }, { "level": 3, "text": "Notes", - "line": 1191 + "line": 1232 }, { "level": 2, "text": "0.4.7 — 2026-01-19", - "line": 1198 + "line": 1239 }, { "level": 3, "text": "Added", - "line": 1204 + "line": 1245 }, { "level": 3, "text": "Changed", - "line": 1209 + "line": 1250 }, { "level": 3, "text": "Philosophy", - "line": 1213 + "line": 1254 }, { "level": 3, "text": "Notes", - "line": 1220 + "line": 1261 }, { "level": 2, "text": "0.4.6 — 2026-01-19", - "line": 1227 + "line": 1268 }, { "level": 3, "text": "Added", - "line": 1233 + "line": 1274 }, { "level": 3, "text": "Changed", - "line": 1239 + "line": 1280 }, { "level": 3, "text": "Behavior", - "line": 1244 + "line": 1285 }, { "level": 2, "text": "0.4.5 — 2026-01-18", - "line": 1255 + "line": 1296 }, { "level": 3, "text": "Added", - "line": 1261 + "line": 1302 }, { "level": 3, "text": "Changed", - "line": 1267 + "line": 1308 }, { "level": 3, "text": "Philosophy", - "line": 1272 + "line": 1313 }, { "level": 3, "text": "Notes", - "line": 1279 + "line": 1320 }, { "level": 2, "text": "0.4.4 — 2026-01-18", - "line": 1286 + "line": 1327 }, { "level": 3, "text": "Added", - "line": 1292 + "line": 1333 }, { "level": 3, "text": "Changed", - "line": 1299 + "line": 1340 }, { "level": 3, "text": "Philosophy", - "line": 1305 + "line": 1346 }, { "level": 2, "text": "0.4.3 — 2026-01-18", - "line": 1313 + "line": 1354 }, { "level": 3, "text": "Added", - "line": 1321 + "line": 1362 }, { "level": 3, "text": "Changed", - "line": 1326 + "line": 1367 }, { "level": 2, "text": "0.4.2 — 2026-01-17", - "line": 1334 + "line": 1375 }, { "level": 3, "text": "Added", - "line": 1340 + "line": 1381 }, { "level": 3, "text": "Changed", - "line": 1353 + "line": 1394 }, { "level": 3, "text": "Philosophy", - "line": 1358 + "line": 1399 }, { "level": 2, "text": "0.4.1 — 2026-01-17", - "line": 1367 + "line": 1408 }, { "level": 3, "text": "Added", - "line": 1373 + "line": 1414 }, { "level": 3, "text": "Changed", - "line": 1383 + "line": 1424 }, { "level": 3, "text": "Notes", - "line": 1394 + "line": 1435 }, { "level": 2, "text": "0.4.0 — 2026-01-17", - "line": 1402 + "line": 1443 }, { "level": 3, "text": "Added", - "line": 1408 + "line": 1449 }, { "level": 3, "text": "Changed", - "line": 1428 + "line": 1469 }, { "level": 3, "text": "Epochs", - "line": 1439 + "line": 1480 }, { "level": 3, "text": "Breaking Changes", - "line": 1446 + "line": 1487 }, { "level": 3, "text": "Notes", - "line": 1454 + "line": 1495 }, { "level": 2, "text": "0.3.1 — 2026-01-17", - "line": 1462 + "line": 1503 }, { "level": 3, "text": "Changed", - "line": 1464 + "line": 1505 }, { "level": 3, "text": "Notes", - "line": 1471 + "line": 1512 }, { "level": 2, "text": "0.3.0 — 2026-01-17", - "line": 1477 + "line": 1518 }, { "level": 3, "text": "Added", - "line": 1479 + "line": 1520 }, { "level": 3, "text": "Changed", - "line": 1492 + "line": 1533 }, { "level": 3, "text": "Deprecated", - "line": 1499 + "line": 1540 }, { "level": 3, "text": "Notes", - "line": 1506 + "line": 1547 }, { "level": 2, "text": "0.1.5 — 2026-01-16 (Superseded by 0.3.0)", - "line": 1514 + "line": 1555 }, { "level": 3, "text": "Added", - "line": 1516 + "line": 1557 }, { "level": 3, "text": "Notes", - "line": 1527 + "line": 1568 }, { "level": 2, "text": "0.1.4 — 2026-01-16", - "line": 1533 + "line": 1574 }, { "level": 3, "text": "Added", - "line": 1535 + "line": 1576 }, { "level": 3, "text": "Changed", - "line": 1543 + "line": 1584 }, { "level": 3, "text": "Notes", - "line": 1548 + "line": 1589 }, { "level": 2, "text": "0.1.3 — 2026-01-16", - "line": 1555 + "line": 1596 }, { "level": 3, "text": "Added", - "line": 1557 + "line": 1598 }, { "level": 3, "text": "Changed", - "line": 1563 + "line": 1604 }, { "level": 3, "text": "Notes", - "line": 1569 + "line": 1610 }, { "level": 2, "text": "0.1.2 — 2026-01-16", - "line": 1575 + "line": 1616 }, { "level": 3, "text": "Added", - "line": 1577 + "line": 1618 }, { "level": 3, "text": "Changed", - "line": 1584 + "line": 1625 }, { "level": 3, "text": "Removed", - "line": 1591 + "line": 1632 }, { "level": 3, "text": "Notes", - "line": 1595 + "line": 1636 }, { "level": 2, "text": "0.1.1 — 2026-01-15", - "line": 1601 + "line": 1642 }, { "level": 3, "text": "Added", - "line": 1603 + "line": 1644 }, { "level": 3, "text": "Established", - "line": 1609 + "line": 1650 }, { "level": 3, "text": "Notes", - "line": 1616 + "line": 1657 }, { "level": 2, "text": "0.1.0 — 2026-01-15", - "line": 1624 + "line": 1665 }, { "level": 3, "text": "Added", - "line": 1626 + "line": 1667 }, { "level": 3, "text": "Notes", - "line": 1649 + "line": 1690 } ], - "heading_count": 226, + "heading_count": 231, "has_frontmatter": true }, { @@ -4439,32 +4465,158 @@ "line": 93 }, { - "level": 3, - "text": "Tier 3: Awareness Without Obligation", - "line": 108 + "level": 3, + "text": "Tier 3: Awareness Without Obligation", + "line": 108 + }, + { + "level": 3, + "text": "Why Tier 3 Exists", + "line": 123 + }, + { + "level": 3, + "text": "Tier 0: Scope Exclusion (Not a Tier)", + "line": 140 + }, + { + "level": 3, + "text": "Tiers Are Not Importance", + "line": 157 + }, + { + "level": 2, + "text": "See Also", + "line": 183 + } + ], + "heading_count": 16, + "has_frontmatter": true + }, + { + "path": "canon/epistemic-surface-extraction.md", + "root": "canon", + "authority_band": "governing", + "authority_inferred": "governing", + "uri": "klappy://canon/epistemic-surface-extraction", + "title": "Epistemic Surface Extraction (ESE)", + "subtitle": "Making visual/audio/video evidence legible to agents without turning it into doctrine.", + "tags": [ + "evidence", + "verification", + "ese", + "surface", + "ocr", + "asr", + "video", + "screenshots", + "recordings" + ], + "stability": "evolving", + "tier": "1", + "audience": "canon", + "exposure": "nav", + "voice": "neutral", + "relevance": "decision", + "execution_posture": "governing", + "headings": [ + { + "level": 1, + "text": "Epistemic Surface Extraction (ESE)", + "line": 2 + }, + { + "level": 2, + "text": "Purpose", + "line": 6 + }, + { + "level": 2, + "text": "Operating Constraints", + "line": 22 + }, + { + "level": 2, + "text": "Outputs (Sidecar Convention)", + "line": 32 + }, + { + "level": 2, + "text": "Invariant Contract (All Modalities)", + "line": 43 + }, + { + "level": 2, + "text": "Segmentation Rules by Modality", + "line": 68 + }, + { + "level": 3, + "text": "Screenshots / Images", + "line": 70 + }, + { + "level": 3, + "text": "Slides / PDFs", + "line": 76 + }, + { + "level": 3, + "text": "Audio Recordings", + "line": 82 + }, + { + "level": 3, + "text": "Video Recordings", + "line": 99 + }, + { + "level": 2, + "text": "Anchor Contract (Audio + Video)", + "line": 111 + }, + { + "level": 3, + "text": "snippet_hash", + "line": 129 + }, + { + "level": 2, + "text": "Surface Bullet Rules", + "line": 143 + }, + { + "level": 2, + "text": "Cross-Reference Relations", + "line": 154 }, { - "level": 3, - "text": "Why Tier 3 Exists", - "line": 123 + "level": 2, + "text": "Containment (Mandatory)", + "line": 168 }, { - "level": 3, - "text": "Tier 0: Scope Exclusion (Not a Tier)", - "line": 140 + "level": 2, + "text": "Promotion Rule", + "line": 180 }, { - "level": 3, - "text": "Tiers Are Not Importance", - "line": 157 + "level": 2, + "text": "Failure Modes", + "line": 190 }, { "level": 2, "text": "See Also", - "line": 183 + "line": 199 + }, + { + "level": 2, + "text": "Provenance", + "line": 207 } ], - "heading_count": 16, + "heading_count": 19, "has_frontmatter": true }, { @@ -9431,6 +9583,129 @@ "heading_count": 11, "has_frontmatter": true }, + { + "path": "docs/CONTENT-MAP.md", + "root": "docs", + "authority_band": "operational", + "authority_inferred": "operational", + "uri": "klappy://docs/content-map", + "title": "Comprehensive Content Map", + "subtitle": "**ODD** = **Outcomes-Driven Development** — see [/odd/README.md](/odd/README.md)", + "tags": [ + "index", + "discovery", + "content", + "map", + "apocrypha", + "all-docs" + ], + "stability": "evolving", + "tier": "1", + "audience": "docs", + "exposure": "nav", + "voice": "neutral", + "relevance": null, + "execution_posture": null, + "headings": [ + { + "level": 1, + "text": "Comprehensive Content Map", + "line": 2 + }, + { + "level": 2, + "text": "Three-Tier Hierarchy (Primary)", + "line": 10 + }, + { + "level": 2, + "text": "Primary Entry Points", + "line": 20 + }, + { + "level": 3, + "text": "ODD Philosophy (`/odd/`)", + "line": 22 + }, + { + "level": 3, + "text": "Canon Governance (`/canon/`)", + "line": 40 + }, + { + "level": 3, + "text": "Implementation Docs (`/docs/`)", + "line": 64 + }, + { + "level": 2, + "text": "Apocrypha (Experimental / Hidden)", + "line": 83 + }, + { + "level": 3, + "text": "`/apocrypha/` — Fragments and Reconstructions", + "line": 87 + }, + { + "level": 3, + "text": "`/apocrypha/fragments-of-the-canon/` — Narrative Fragments", + "line": 96 + }, + { + "level": 3, + "text": "`/apocrypha/reconstructions/` — Reconstruction Attempts", + "line": 107 + }, + { + "level": 3, + "text": "`/canon/apocrypha/` — Canon-Adjacent Apocrypha", + "line": 116 + }, + { + "level": 2, + "text": "Supporting Areas", + "line": 125 + }, + { + "level": 3, + "text": "About (`/about/`)", + "line": 127 + }, + { + "level": 3, + "text": "Projects (`/projects/`)", + "line": 136 + }, + { + "level": 3, + "text": "Products (`/products/`)", + "line": 145 + }, + { + "level": 3, + "text": "Infrastructure (`/infra/`)", + "line": 154 + }, + { + "level": 2, + "text": "Key Acronyms", + "line": 165 + }, + { + "level": 2, + "text": "Discovery Tips", + "line": 177 + }, + { + "level": 2, + "text": "See Also", + "line": 188 + } + ], + "heading_count": 19, + "has_frontmatter": true + }, { "path": "docs/context-packs-and-projection-detail.md", "root": "docs", @@ -11834,26 +12109,34 @@ "root": "docs", "authority_band": "operational", "authority_inferred": "operational", - "uri": null, + "uri": "oddkit://about", "title": "About oddkit", - "subtitle": null, - "tags": [], - "stability": null, - "tier": null, - "audience": null, - "exposure": null, - "voice": null, + "subtitle": "**ODD** = **Outcomes-Driven Development** — see [/odd/README.md](/odd/README.md) for the full philosophy.", + "tags": [ + "oddkit", + "odd", + "definition", + "outcomes-driven-development", + "what-is-odd", + "about", + "orientation" + ], + "stability": "stable", + "tier": "1", + "audience": "docs", + "exposure": "nav", + "voice": "neutral", "relevance": null, "execution_posture": null, "headings": [ { "level": 1, "text": "About oddkit", - "line": 1 + "line": 2 } ], "heading_count": 1, - "has_frontmatter": false + "has_frontmatter": true }, { "path": "docs/oddkit/epistemic-instructions.md", @@ -12151,6 +12434,8 @@ "subtitle": "A practical guide for understanding oddkit behavior, outcomes, and next actions.", "tags": [ "oddkit", + "odd", + "outcomes-driven-development", "orchestrator", "librarian", "validation", @@ -12172,47 +12457,47 @@ { "level": 2, "text": "What Oddkit Is", - "line": 11 + "line": 13 }, { "level": 2, "text": "High-Level Pipeline", - "line": 24 + "line": 26 }, { "level": 2, "text": "Interpreting Outcomes", - "line": 55 + "line": 57 }, { "level": 2, "text": "Understanding Warnings", - "line": 68 + "line": 70 }, { "level": 2, "text": "Confidence & Arbitration", - "line": 84 + "line": 86 }, { "level": 2, "text": "What Oddkit Will Never Do", - "line": 99 + "line": 101 }, { "level": 2, "text": "Epistemic Challenge (Behavioral Doctrine)", - "line": 113 + "line": 115 }, { "level": 2, "text": "Where To Look Next", - "line": 129 + "line": 131 }, { "level": 2, "text": "Summary", - "line": 137 + "line": 139 } ], "heading_count": 10, @@ -13111,7 +13396,7 @@ "authority_inferred": "operational", "uri": "klappy://docs", "title": "Implementation Documentation", - "subtitle": "How klappy.dev implements ODD. This is the reference implementation, not the philosophy.", + "subtitle": "How klappy.dev implements **ODD (Outcomes-Driven Development)**. This is the reference implementation, not the philosophy.", "tags": [ "docs", "implementation", @@ -13134,60 +13419,65 @@ { "level": 2, "text": "🗺️ Where You Are in the Hierarchy", - "line": 6 + "line": 8 }, { "level": 2, "text": "✅ What Belongs in /docs/", - "line": 18 + "line": 20 }, { "level": 2, "text": "🚫 What Does NOT Belong in /docs/", - "line": 31 + "line": 33 }, { "level": 2, "text": "📁 Contents", - "line": 47 + "line": 49 + }, + { + "level": 3, + "text": "Discovery & Navigation", + "line": 51 }, { "level": 3, "text": "Workflows & Procedures", - "line": 49 + "line": 57 }, { "level": 3, "text": "Reference Documents", - "line": 59 + "line": 67 }, { "level": 3, "text": "Templates", - "line": 68 + "line": 76 }, { "level": 3, "text": "Subfolders", - "line": 77 + "line": 85 }, { "level": 2, "text": "🔗 Relationship to ODD & Canon", - "line": 90 + "line": 98 }, { "level": 2, "text": "🧹 Epistemic Hygiene Rules", - "line": 124 + "line": 132 }, { "level": 2, "text": "👀 See Also", - "line": 133 + "line": 141 } ], - "heading_count": 12, + "heading_count": 13, "has_frontmatter": true }, { @@ -13665,7 +13955,7 @@ "authority_inferred": "operational", "uri": "oddkit://why", "title": "Why oddkit Exists", - "subtitle": "oddkit helps agents verify truth — not remember conversations.", + "subtitle": "**ODD** = **Outcomes-Driven Development** — see [/odd/README.md](/odd/README.md) for the full philosophy.", "tags": [ "orientation", "oddkit", @@ -13688,22 +13978,22 @@ { "level": 2, "text": "What oddkit Is (and Is Not)", - "line": 20 + "line": 22 }, { "level": 2, "text": "When oddkit Is Used", - "line": 40 + "line": 42 }, { "level": 2, "text": "Why This Is Different", - "line": 57 + "line": 59 }, { "level": 2, "text": "How to Learn More", - "line": 71 + "line": 73 } ], "heading_count": 5, @@ -15625,11 +15915,15 @@ "authority_band": "governing", "authority_inferred": "governing", "uri": "klappy://odd", - "title": "Outcomes-Driven Development", + "title": "Outcomes-Driven Development (ODD)", "subtitle": null, "tags": [ "odd", - "index" + "index", + "definition", + "outcomes-driven-development", + "what-is-odd", + "methodology" ], "stability": "stable", "tier": "1", @@ -15678,7 +15972,11 @@ "subtitle": "A governance framework for human-AI collaboration that optimizes learning, not execution.", "tags": [ "odd", - "philosophy" + "philosophy", + "outcomes-driven-development", + "manifesto", + "governance", + "definition" ], "stability": "stable", "tier": "2", @@ -16022,7 +16320,9 @@ "tags": [ "odd", "orientation", - "mental-model" + "mental-model", + "outcomes-driven-development", + "hierarchy" ], "stability": "semi_stable", "tier": "3", @@ -16192,15 +16492,20 @@ "authority_band": "governing", "authority_inferred": "governing", "uri": "klappy://public/odd", - "title": "ODD Manifesto — Public", + "title": "What is ODD? — Outcomes-Driven Development", "subtitle": "ODD is about preserving intent without freezing execution.", "tags": [ "odd", + "definition", + "outcomes-driven-development", + "what-is-odd", + "methodology", + "philosophy", "public", "overview" ], "stability": "semi_stable", - "tier": "0", + "tier": "1", "audience": "public", "exposure": "nav", "voice": "neutral", @@ -16407,7 +16712,10 @@ "odd", "terminology", "disambiguation", - "boundary" + "boundary", + "definition", + "outcomes-driven-development", + "glossary" ], "stability": "evolving", "tier": "1", @@ -16444,116 +16752,121 @@ }, { "level": 3, - "text": "Outcome", + "text": "ODD (Outcomes-Driven Development)", "line": 46 }, + { + "level": 3, + "text": "Outcome", + "line": 60 + }, { "level": 3, "text": "Evidence", - "line": 56 + "line": 70 }, { "level": 3, "text": "Artifact", - "line": 66 + "line": 80 }, { "level": 3, "text": "Elevation", - "line": 76 + "line": 90 }, { "level": 3, "text": "Canon", - "line": 89 + "line": 103 }, { "level": 3, "text": "Attempt", - "line": 99 + "line": 113 }, { "level": 3, "text": "Lane", - "line": 112 + "line": 126 }, { "level": 3, "text": "Maturity", - "line": 122 + "line": 136 }, { "level": 2, "text": "Disambiguation Table", - "line": 135 + "line": 149 }, { "level": 2, "text": "Anti-Patterns in Language", - "line": 147 + "line": 161 }, { "level": 3, "text": "Confidence as Evidence", - "line": 149 + "line": 163 }, { "level": 3, "text": "Explanation as Proof", - "line": 152 + "line": 166 }, { "level": 3, "text": "Activity as Progress", - "line": 155 + "line": 169 }, { "level": 3, "text": "Artifact as Outcome", - "line": 158 + "line": 172 }, { "level": 2, "text": "Boundary Conditions", - "line": 163 + "line": 177 }, { "level": 3, "text": "What This Document Does NOT Define", - "line": 165 + "line": 179 }, { "level": 3, "text": "When to Extend", - "line": 171 + "line": 185 }, { "level": 2, "text": "Usage Guidelines", - "line": 182 + "line": 196 }, { "level": 3, "text": "For Authors", - "line": 184 + "line": 198 }, { "level": 3, "text": "For Reviewers", - "line": 190 + "line": 204 }, { "level": 3, "text": "For Canon Documents", - "line": 195 + "line": 209 }, { "level": 2, "text": "Evolution Process", - "line": 202 + "line": 216 } ], - "heading_count": 27, + "heading_count": 28, "has_frontmatter": true } ] diff --git a/public/content/canon/CHANGELOG.md b/public/content/canon/CHANGELOG.md index 67689468..1ee62a0e 100644 --- a/public/content/canon/CHANGELOG.md +++ b/public/content/canon/CHANGELOG.md @@ -18,6 +18,47 @@ This changelog tracks changes to the **Canon pack** as a whole. The Canon uses **pack-level versioning** (one version number) rather than per-file versioning. Per-file versions are intentionally omitted to reduce ceremony and prevent metadata rot. +## 0.28.0 — 2026-02-05 + +**ODD Acronym Visibility + ESE Promotion + Content Discovery** + +This release addresses LLM hallucination of the ODD acronym, promotes Epistemic Surface Extraction (ESE) from apocrypha to canon, and adds comprehensive content discovery. + +### Added + +- **Epistemic Surface Extraction (ESE)** (`/canon/epistemic-surface-extraction.md`) — Promoted from apocrypha. Defines how to make non-text evidence (screenshots, recordings, videos) legible to agents without turning them into doctrine. Establishes sidecar convention (`.surface.json`, `.surface.md`), segmentation rules by modality, anchor contracts for time-based media, and mandatory containment clauses. + +- **Comprehensive Content Map** (`/docs/CONTENT-MAP.md`) — Discovery index for ALL repository content including apocrypha. Surfaces hidden/experimental docs, lists key acronyms (ODD, ESE, MCP, PRD, ADR), and provides navigation tips. + +### Changed + +- **ODD Acronym Definitions** — Added "ODD = Outcomes-Driven Development" callouts to key oddkit entry points to prevent LLM hallucination: + - `/docs/WHY.md` — Added callout at top + link in "How to Learn More" + - `/docs/oddkit/ABOUT.md` — Added callout + links to WHY.md and /odd/README.md + - `/docs/README.md` — Expanded "implements ODD" to include full acronym definition + +- **Verification & Evidence** (`/canon/verification-and-evidence.md`) — Added ESE to "See Also" section + +- **Root README** — Added CONTENT-MAP.md to "Start Here" section + +- **Apocrypha ESE** (`/apocrypha/artifacts/SURFACE-EXTRACTION.md`) — Marked as PROMOTED with redirect to canonical version + +### Philosophy + +- **Acronyms must be visible at entry points** — LLMs entering through oddkit documentation never saw "Outcomes-Driven Development" because the acronym was only defined in `/odd/README.md`. Entry points must define or link to acronym expansions. + +- **ESE makes evidence legible** — Screenshots and recordings are evidence but were invisible to agents without structured extraction. ESE provides the protocol without canonizing the artifacts themselves. + +- **Discovery includes experimental content** — Apocrypha and hidden docs are valuable for exploration but were hard to find. CONTENT-MAP makes all content navigable. + +### Notes + +- ESE is now the canonical reference for evidence extraction from non-text artifacts +- CONTENT-MAP is intentionally comprehensive (includes apocrypha) and can be filtered later +- Original apocrypha ESE doc retained with PROMOTED notice for provenance + +--- + ## 0.27.0 — 2026-01-31 **Scope Over Folders — Path Independence Invariant** diff --git a/public/content/canon/epistemic-surface-extraction.md b/public/content/canon/epistemic-surface-extraction.md new file mode 100644 index 00000000..6bb9b25d --- /dev/null +++ b/public/content/canon/epistemic-surface-extraction.md @@ -0,0 +1,221 @@ +--- +uri: klappy://canon/epistemic-surface-extraction +title: "Epistemic Surface Extraction (ESE)" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: evolving +tags: ["evidence", "verification", "ese", "surface", "ocr", "asr", "video", "screenshots", "recordings"] +relevance: decision +execution_posture: governing +--- + +# Epistemic Surface Extraction (ESE) + +> Making visual/audio/video evidence legible to agents without turning it into doctrine. + +## Purpose + +Many verification artifacts are not text-first: screenshots, recordings, videos, PDF slides. Without a structured "surface," they become invisible influence: present, persuasive, and unauditable. + +**Epistemic Surface Extraction (ESE)** is a repeatable method to extract *what an artifact asserts and depicts* in a way that: + +- makes evidence **discoverable** and **searchable** for humans and agents +- preserves **emphasis** and **structure** (not just words) +- prevents **accidental canonization** +- maintains **contestability** + +ESE is not "OCR." +ESE is **awareness extraction**. + +--- + +## Operating Constraints + +- MUST produce sidecar files for any non-text evidence artifact +- MUST include containment clause marking surfaces as non-canonical +- MUST use anchor contracts for time-based media (audio/video) +- MUST NOT treat surface extractions as doctrine or instruction +- MUST reference source artifacts explicitly + +--- + +## Outputs (Sidecar Convention) + +For an artifact `artifact.ext`, produce: + +- `artifact.surface.json` — authoritative, machine-usable surface (source-of-truth) +- `artifact.surface.md` — human-readable rendering (derived from JSON when possible) + +Artifacts remain **non-canonical** by default. + +--- + +## Invariant Contract (All Modalities) + +Every `*.surface.json` MUST contain: + +1. **Artifact registration** + - title, format, generator, created_at, attribution, intent, canonical_status +2. **Segmentation spec** + - modality, unit, method, anchor stability notes +3. **Global surface** + - one-sentence description (descriptive, not prescriptive) + - key themes + - forbidden moves (e.g., "do not treat as instruction") +4. **Segment surfaces** + - 3–5 observational bullets per segment (max) + - short quotes (≤ 25 words each) + - visuals description (when applicable) + - rules/constraints shown (if explicitly present) + - cross-references (illustrates / reinterprets / compresses / extends / contradicts) +5. **Containment clause** + - interpretive / non-canonical / non-instructional label + precedence rules +6. **Provenance** + - extraction method and human review status + +--- + +## Segmentation Rules by Modality + +### Screenshots / Images + +- **unit:** `frame` +- **anchor_type:** `frame_index` (or `1`) +- **segments:** 1 per image (unless intentionally subdividing regions) + +### Slides / PDFs + +- **unit:** `page` +- **anchor_type:** `page_number` +- **segments:** 1 per page + +### Audio Recordings + +Audio is time-structured. Meaning may rely on emphasis and pacing. + +Choose segmentation based on source: + +- **multi-speaker:** `unit = speaker_turn` (preferred) +- **single-speaker:** `unit = topic_block` (preferred) + +Anchors MUST be stable: + +- **anchor_type:** `timestamp+hash` (required) + +Where: +- `timestamp_start` / `timestamp_end` are included +- `snippet_hash` is included (see Anchor Contract below) + +### Video Recordings + +Video contains two channels: speech + visuals. + +- **unit:** `scene` (preferred) or `topic_block` +- **anchor_type:** `timestamp+hash` (required) +- Segment surfaces SHOULD include: + - spoken surface (ASR-derived quotes + bullets) + - visual surface (what appears on screen; on-screen text; diagrams; notable gestures) + +--- + +## Anchor Contract (Audio + Video) + +Timestamps alone can drift if: +- the file is trimmed +- the file is re-encoded +- a different cut is produced + +Transcript text alone can drift if: +- ASR improves +- punctuation changes +- casing or normalization changes + +Therefore anchors MUST include BOTH: + +- `timestamp_start` +- `timestamp_end` +- `snippet_hash` + +### snippet_hash + +A short, stable identifier derived from a transcript snippet near the start of the segment. + +Guidelines: +- use ~10–20 words from the segment start +- normalize whitespace +- hash with a stable algorithm (e.g., sha256) +- store only the hash (not the full snippet) if privacy is a concern + +This creates an anchor that remains usable under minor shifts. + +--- + +## Surface Bullet Rules + +Per segment: +- 3–5 bullets maximum +- observational / descriptive language +- avoid "should/must" unless quoting the artifact +- do not introduce new doctrine +- if making an inference, label it explicitly as "Inference: …" + +--- + +## Cross-Reference Relations + +Use one of: + +- `illustrates` — directly depicts content from a referenced doc +- `compresses` — summarizes or condenses referenced content +- `reinterprets` — reframes the meaning without adding new facts +- `extends` — adds new claims beyond the referenced source (**high risk**) +- `contradicts` — conflicts with referenced source + +Default to `illustrates` or `compresses`. + +--- + +## Containment (Mandatory) + +Every surface MUST include a containment clause similar to: + +> This artifact is interpretive and non-canonical. It may illustrate themes but does not define rules. If it can be safely treated as instruction, it has failed. + +Precedence: +- Canon overrides surface artifacts. +- Surface artifacts override nothing. + +--- + +## Promotion Rule + +Surfaces can inform canon edits, but: + +- **Artifacts do not become canon.** +- Only *separately authored canon changes* can be promoted. +- If a surface reveals a durable insight, promote the insight **by editing canon**, not by referencing the artifact as authority. + +--- + +## Failure Modes + +- **Raw Dump**: Extracting text without structure or emphasis +- **Doctrine Creep**: Treating a surface extraction as instruction +- **Anchor Drift**: Using timestamps alone without hash anchors +- **Missing Containment**: Omitting the non-canonical warning + +--- + +## See Also + +- [Verification & Evidence](/canon/verification-and-evidence.md) +- [Visual Proof Standards](/canon/visual-proof.md) +- [Definition of Done](/canon/definition-of-done.md) + +--- + +## Provenance + +Promoted from `/apocrypha/artifacts/SURFACE-EXTRACTION.md` to Canon. diff --git a/public/content/canon/meta/pack.json b/public/content/canon/meta/pack.json index ac78fea4..0428566a 100644 --- a/public/content/canon/meta/pack.json +++ b/public/content/canon/meta/pack.json @@ -1,7 +1,7 @@ { "name": "klappy-canon", - "version": "0.26.0", - "updated_at": "2026-01-31", + "version": "0.28.0", + "updated_at": "2026-02-05", "description": "Canonical orientation, constraints, decision rules, evidence policies, and ODD appendices used across klappy.dev.", "public_entrypoint": "klappy://public/odd", "canon_entrypoint": "klappy://meta/canon-index", diff --git a/public/content/canon/verification-and-evidence.md b/public/content/canon/verification-and-evidence.md index 84a94304..5eb7a5ad 100644 --- a/public/content/canon/verification-and-evidence.md +++ b/public/content/canon/verification-and-evidence.md @@ -164,6 +164,7 @@ Lane rules are **instantiations**, not exceptions. ## See Also +- [Epistemic Surface Extraction (ESE)](/canon/epistemic-surface-extraction.md) — Making screenshots, recordings, and video evidence legible - [Visual Proof Standards](/canon/visual-proof.md) - [Definition of Done](/canon/definition-of-done.md) - [Constraints](/canon/constraints.md) diff --git a/public/content/manifest.json b/public/content/manifest.json index d3f44154..3f7e5b36 100644 --- a/public/content/manifest.json +++ b/public/content/manifest.json @@ -1,8 +1,8 @@ { "pack": { "name": "klappy-canon", - "version": "0.26.0", - "updated_at": "2026-01-31", + "version": "0.28.0", + "updated_at": "2026-02-05", "description": "Canonical orientation, constraints, decision rules, evidence policies, and ODD appendices used across klappy.dev.", "public_entrypoint": "klappy://public/odd", "canon_entrypoint": "klappy://meta/canon-index", @@ -498,6 +498,28 @@ "stability": "evolving", "tags": [] }, + { + "uri": "klappy://canon/epistemic-surface-extraction", + "path": "/canon/epistemic-surface-extraction.md", + "title": "Epistemic Surface Extraction (ESE)", + "type": "text/markdown", + "audience": "canon", + "exposure": "nav", + "tier": 1, + "voice": "neutral", + "stability": "evolving", + "tags": [ + "evidence", + "verification", + "ese", + "surface", + "ocr", + "asr", + "video", + "screenshots", + "recordings" + ] + }, { "uri": "klappy://canon/defaults/evidence-intake", "path": "/canon/defaults/evidence-intake.md", @@ -680,7 +702,9 @@ "tags": [ "odd", "orientation", - "mental-model" + "mental-model", + "outcomes-driven-development", + "hierarchy" ] }, { @@ -817,30 +841,13 @@ "stability": "stable", "tags": [ "odd", - "philosophy" + "philosophy", + "outcomes-driven-development", + "manifesto", + "governance", + "definition" ] }, - { - "uri": "klappy://public/odd", - "path": "/odd/README.md", - "title": "ODD Manifesto — Public", - "type": "text/markdown", - "audience": "public", - "exposure": "nav", - "tier": 0, - "voice": "neutral", - "stability": "semi_stable", - "tags": [ - "odd", - "public", - "overview" - ], - "assets": { - "practice_video": "/assets/odd/odd-in-practice.mp4", - "misconception_image": "/assets/odd/odd-is-not-a-framework.png", - "deep_dive_audio": "/assets/odd/why-evidence-beats-confidence.m4a" - } - }, { "uri": "klappy://canon/agents/odd-map-navigator", "path": "/canon/agents/odd-map-navigator.md", @@ -965,7 +972,7 @@ { "uri": "klappy://odd", "path": "/odd/index.md", - "title": "Outcomes-Driven Development", + "title": "Outcomes-Driven Development (ODD)", "type": "text/markdown", "audience": "canon", "exposure": "nav", @@ -974,7 +981,11 @@ "stability": "stable", "tags": [ "odd", - "index" + "index", + "definition", + "outcomes-driven-development", + "what-is-odd", + "methodology" ] }, { @@ -1342,6 +1353,32 @@ "promotion" ] }, + { + "uri": "klappy://public/odd", + "path": "/odd/README.md", + "title": "What is ODD? — Outcomes-Driven Development", + "type": "text/markdown", + "audience": "public", + "exposure": "nav", + "tier": 1, + "voice": "neutral", + "stability": "semi_stable", + "tags": [ + "odd", + "definition", + "outcomes-driven-development", + "what-is-odd", + "methodology", + "philosophy", + "public", + "overview" + ], + "assets": { + "practice_video": "/assets/odd/odd-in-practice.mp4", + "misconception_image": "/assets/odd/odd-is-not-a-framework.png", + "deep_dive_audio": "/assets/odd/why-evidence-beats-confidence.m4a" + } + }, { "uri": "klappy://about/why-this-exists", "path": "/about/why-this-exists.md", diff --git a/public/content/odd/README.md b/public/content/odd/README.md index ae526051..d856e79a 100644 --- a/public/content/odd/README.md +++ b/public/content/odd/README.md @@ -1,12 +1,12 @@ --- uri: klappy://public/odd -title: "ODD Manifesto — Public" +title: "What is ODD? — Outcomes-Driven Development" audience: public exposure: nav -tier: 0 +tier: 1 voice: neutral stability: semi_stable -tags: ["odd", "public", "overview"] +tags: ["odd", "definition", "outcomes-driven-development", "what-is-odd", "methodology", "philosophy", "public", "overview"] relevance: routing execution_posture: routing assets: {"practice_video":"/assets/odd/odd-in-practice.mp4","misconception_image":"/assets/odd/odd-is-not-a-framework.png","deep_dive_audio":"/assets/odd/why-evidence-beats-confidence.m4a"} diff --git a/public/content/odd/index.md b/public/content/odd/index.md index 690f82f8..f4306096 100644 --- a/public/content/odd/index.md +++ b/public/content/odd/index.md @@ -1,12 +1,13 @@ --- uri: klappy://odd -title: "Outcomes-Driven Development" +title: "Outcomes-Driven Development (ODD)" +subtitle: "ODD = Outcomes-Driven Development — the philosophical and operational foundation for this repository." audience: canon exposure: nav tier: 1 voice: neutral stability: stable -tags: ["odd", "index"] +tags: ["odd", "index", "definition", "outcomes-driven-development", "what-is-odd", "methodology"] relevance: routing execution_posture: routing --- diff --git a/public/content/odd/manifesto.md b/public/content/odd/manifesto.md index b82c8fd3..01caccf3 100644 --- a/public/content/odd/manifesto.md +++ b/public/content/odd/manifesto.md @@ -6,7 +6,7 @@ exposure: nav tier: 2 voice: neutral stability: stable -tags: ["odd", "philosophy"] +tags: ["odd", "philosophy", "outcomes-driven-development", "manifesto", "governance", "definition"] relevance: background execution_posture: exploratory --- diff --git a/public/content/odd/orientation-map.md b/public/content/odd/orientation-map.md index bd66adb8..9a542ac7 100644 --- a/public/content/odd/orientation-map.md +++ b/public/content/odd/orientation-map.md @@ -6,7 +6,7 @@ exposure: nav tier: 3 voice: neutral stability: semi_stable -tags: ["odd", "orientation", "mental-model"] +tags: ["odd", "orientation", "mental-model", "outcomes-driven-development", "hierarchy"] relevance: supporting execution_posture: operational --- diff --git a/public/content/odd/terminology.md b/public/content/odd/terminology.md index 22a1a9c0..893bb14f 100644 --- a/public/content/odd/terminology.md +++ b/public/content/odd/terminology.md @@ -8,7 +8,7 @@ exposure: nav tier: 1 voice: neutral stability: evolving -tags: ["odd", "terminology", "disambiguation", "boundary"] +tags: ["odd", "terminology", "disambiguation", "boundary", "definition", "outcomes-driven-development", "glossary"] relevance: supporting execution_posture: operational --- @@ -57,6 +57,20 @@ If terminology lived under `canon/`, language would appear post hoc. ODD would l ## Core Terms +### ODD (Outcomes-Driven Development) + +**ODD meaning:** Outcomes-Driven Development — an approach to building software that prioritizes real-world results over artifacts. In an AI-accelerated environment, the limiting factor is no longer production speed; it is clarity of intent, quality of verification, and the ability to choose among outcomes. ODD makes those constraints explicit. + +**Not:** A framework, a fixed workflow, or a claim that outcomes can be fully predicted. + +**Core thesis:** The primary job of development is not writing code. It is defining outcomes, enforcing constraints, and verifying reality. AI accelerates execution; governance preserves trust. + +**Test:** Are decisions governed by verifiable outcomes, or by artifacts and activity? + +**See:** [/odd/README.md](/odd/README.md) for the public introduction, [/odd/manifesto.md](/odd/manifesto.md) for the extended operational framework. + +--- + ### Outcome **ODD meaning:** A verifiable state of reality that can be demonstrated, not just described.