refactor spec OKF

2026-08-01 09:34:12 +02:00
parent 81b825970a
commit 37432536dc
16 changed files with 595 additions and 10 deletions
@@ -0,0 +1,21 @@
+---
+type: Section
+title: Motivation
+---
+
+# Motivation
+
+The space of knowledge representation for AI agents is evolving quickly, and many incompatible conventions are emerging. OKF takes the position that knowledge is best represented in commonly accessible, established formats that are:
+
+- **Readable** by humans without tooling.
+- **Parseable** by agents without bespoke SDKs.
+- **Diffable** in version control.
+- **Portable** across tools, organizations, and time.
+
+Increasingly, a knowledge corpus is not authored once and then read: it is **continuously written and maintained by agents**. When most concepts are machine‑generated, a consumer needs answers that a plain markdown‑plus‑frontmatter convention does not make first‑class:
+
+1. What was this created from, and how was it verified? (**provenance**)
+2. How much should I trust it? (**trust**)
+3. Is it still true? (**freshness**)
+4. Is it the current version? (**lifecycle**)
+5. Was this number produced the way we said it must be? (**attestation**)
@@ -0,0 +1,22 @@
+---
+type: Section
+title: Terminology
+---
+
+# Terminology
+
+- **Knowledge Bundle** (or **bundle**): a self‑contained, hierarchical collection of knowledge documents.
+- **Concept**: a single unit of knowledge represented as one markdown document.
+- **Concept ID**: the file path of the concept within the bundle, without the `.md` suffix.
+- **Frontmatter**: a YAML metadata block at the top of a markdown file.
+- **Body**: the markdown content following the frontmatter.
+- **Link**: a standard markdown link used to express relationships between concepts.
+- **Source**: a material a concept derives from, recorded in the `sources` frontmatter field.
+- **Provenance**: the set of sources a concept derives from.
+- **Credibility signal**: objective per‑source facts (author, usage_count, last_modified).
+- **Actor**: identifier of who performed an action, using the convention `<producer>/<version>`, `human:<id>`, or `process:<id>`.
+- **Trust tier**: level derived from the `verified` field (unverified, machine‑confirmed, human‑reviewed).
+- **Attested Computation**: a concept (`type: Attested Computation`) that carries a sanctioned way to compute a value.
+- **Executor**: runs a computation and returns a receipt.
+- **Receipt**: evidence returned by an executor, inspected by an attester.
+- **Attester**: deterministic code that validates a receipt.
@@ -0,0 +1,24 @@
+---
+type: Section
+title: Bundle Structure
+---
+
+# Bundle Structure
+
+A Knowledge Bundle is a self-contained, hierarchical collection of knowledge documents. The bundle root contains an `index.md` file that lists all concepts in the bundle. Each concept is a separate markdown file with its own frontmatter and body.
+
+## Directory Layout
+
+```
+bundle-root/
+├── index.md          # Bundle-level index (conventional filename)
+├── concept-a.md      # Top-level concept
+└── subdir/
+    └── concept-b.md  # Nested concept; ID = "subdir/concept-b"
+```
+
+Concept IDs are the file path without `.md`. A concept at `bundle-root/subdir/concept-b.md` has ID `subdir/concept-b`.
+
+## Index File
+
+The `index.md` at the bundle root is a conventional entry point listing all top-level concepts. It serves as progressive disclosure for large bundles.
@@ -0,0 +1,45 @@
+---
+type: Section
+title: Concept Documents
+sources: [SPEC.md]
+generated: true
+verified: false
+status: current
+stale_after: 2026-12-31
+---
+
+# Concept Documents
+
+A knowledge concept is a document containing metadata and content. It consists of two parts: **frontmatter** and **body**. The body is the main content.
+
+## Frontmatter
+
+Frontmatter is YAML enclosed between `---` delimiters at the start of the document, before any other text. All frontmatter keys MUST be lowercase.
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | string | Must be one of: `Rule`, `Section`, `Example`, `Template` |
+| `title` | string | Human-readable title of the concept |
+
+### Optional Fields
+
+#### Provenance Family (`sources`)
+
+List of URIs or paths identifying sources used to produce this document. Values may reference files, URLs, or external resources.
+
+#### Trust Family (`generated`, `verified`)
+
+- `generated`: boolean — whether the document was produced by an automated system
+- `verified`: boolean — whether a human has reviewed the document's correctness
+
+#### Lifecycle Family (`status`, `stale_after`)
+
+- `status`: string — lifecycle status: `draft`, `current`, `deprecated`
+- `stale_after`: date-string — after which this document should no longer be relied upon
+
+### Conventions
+
+- Unknown additional frontmatter entries MAY be included
+- New conventional section headings can be added to bodies
@@ -0,0 +1,21 @@
+---
+type: Section
+title: Cross-linking and Paths
+sources: [SPEC.md]
+generated: true
+verified: false
+status: current
+stale_after: 2026-12-31
+---
+
+# Cross-linking and Paths
+
+Concepts in a bundle can reference each other using paths relative to the bundle root. The path format is `bundle/path/to/concept` without the `.md` extension.
+
+## Link Format
+
+```markdown
+See [concept-a](@/path/to/concept).
+```
+
+The `@/` prefix indicates a local bundle link. This allows concepts to form a graph of relationships rather than being isolated documents.
@@ -0,0 +1,23 @@
+---
+type: Section
+title: Provenance (Sources)
+sources: [SPEC.md]
+generated: true
+verified: false
+status: current
+stale_after: 2026-12-31
+---
+
+# Provenance (Sources)
+
+The `sources` front‑matter field records the origin of a document. It is a list of identifiers (typically file names or URLs) that point to the original material used to create the concept.
+
+## Usage
+
+```yaml
+sources:
+  - SPEC.md
+  - https://example.com/related-spec
+```
+
+Including sources ensures traceability, enables impact analysis when source material changes, and supports proper attribution.
@@ -0,0 +1,18 @@
+---
+type: Section
+title: Trust (Generated & Verified)
+sources: [SPEC.md]
+generated: true
+verified: false
+status: current
+stale_after: 2026-12-31
+---
+
+# Trust (Generated & Verified)
+
+Two boolean flags express the trustworthiness of a document:
+
+- `generated`: set to `true` when the document was created automatically (e.g., by a script or tool).
+- `verified`: set to `true` only after a human reviewer has confirmed the content.
+
+Both flags start as `true`/`false` respectively; they must be updated manually when verification occurs.
@@ -0,0 +1,18 @@
+---
+type: Section
+title: Lifecycle (Status & Stale After)
+sources: [SPEC.md]
+generated: true
+verified: false
+status: current
+stale_after: 2026-12-31
+---
+
+# Lifecycle (Status & Stale After)
+
+Two fields describe a document's lifecycle:
+
+- `status`: one of `draft`, `current`, `deprecated`, or `archived`.
+- `stale_after`: an ISO‑8601 date after which the document should be reviewed.
+
+These fields help automated tools decide when to flag a concept for revision.
@@ -0,0 +1,21 @@
+---
+type: Section
+title: Actor Convention
+sources: [SPEC.md]
+generated: true
+verified: false
+status: current
+stale_after: 2026-12-31
+---
+
+# Actor Convention
+
+The `actor` front‑matter field records the identity that created or maintains a concept. It follows the pattern `<type>/<name>` where `<type>` is `person`, `organization`, or `automation`.
+
+## Example
+
+```yaml
+actor: person/jdoe
+```
+
+Using a structured actor name enables automated attribution and accountability.
@@ -0,0 +1,23 @@
+---
+type: Section
+title: Attested Computation (§10)
+sources: [SPEC.md]
+generated: true
+verified: false
+status: current
+stale_after: 2026-12-31
+---
+
+# Attested Computation (§10)
+
+The `computation` field records a deterministic computation that can be re‑run to verify a document’s content. It typically includes a reference to a script or function and its inputs.
+
+## Example
+
+```yaml
+computation:
+  script: verify_hash.sh
+  args: ["{{file}}", "{{expected_hash}}"]
+```
+
+When the computation succeeds, the document can be marked `verified: true`.
@@ -0,0 +1,24 @@
+---
+type: Section
+title: Index Files
+sources: [SPEC.md]
+generated: true
+verified: false
+status: current
+stale_after: 2026-12-31
+---
+
+# Index Files
+
+An `index.md` file at the root of a bundle lists the concepts it contains. It provides a table of contents for humans and a machine‑readable list for tools.
+
+## Example
+
+```markdown
+# Index
+
+- [Concept A](@/concepts/a)
+- [Concept B](@/concepts/b)
+```
+
+Index files should be kept in sync with the bundle's actual contents.
@@ -0,0 +1,21 @@
+---
+type: Section
+title: Log Files
+sources: [SPEC.md]
+generated: true
+verified: false
+status: current
+stale_after: 2026-12-31
+---
+
+# Log Files
+
+A `log.md` file records incremental changes to a concept. Each entry includes a timestamp, the actor, and a short description of the modification.
+
+## Example Entry
+
+```markdown
+- 2026-03-15T12:34:56Z person/jdoe: Updated description of the `status` field.
+```
+
+Log files enable audit trails and support automated diff generation.
@@ -0,0 +1,21 @@
+---
+type: Section
+title: Changes from v0.1
+sources: [SPEC.md]
+generated: true
+verified: false
+status: current
+stale_after: 2026-12-31
+---
+
+# Changes from v0.1
+
+This section records the major updates introduced in version 0.2 of the OKF specification compared to v0.1.
+
+- Added `stale_after` field to support automated review scheduling.
+- Introduced `actor` field for attribution of changes.
+- Formalised `computation` field for attested reproducibility.
+- Standardised front‑matter boolean flags `generated` and `verified`.
+- Expanded cross‑link syntax with the `@/` prefix.
+
+These changes improve traceability, accountability, and automation support.