refactor spec OKF
This commit is contained in:
Jérôme Bousquié
+22
-10
@@ -1,24 +1,36 @@
|
||||
---
|
||||
type: Reference
|
||||
title: IAgent Documentation Rules
|
||||
description: Rules and guidelines for documentation in the IAgent project, following OKF v0.2 specification
|
||||
type: Rule
|
||||
title: Documentation Rules
|
||||
description: Rules and guidelines for documentation in the WSG project, following OKF v0.2 specification
|
||||
resource: https://github.com/wsg-project/wsg/blob/main/docs/rules/DOCUMENTATION.md
|
||||
tags: [documentation, guidelines, standards]
|
||||
status: stable
|
||||
generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
|
||||
sources: [{ ref: SPEC.md }]
|
||||
verified: { by: "human:jerome", at: 2026-07-31T00:00:00Z }
|
||||
status: active
|
||||
stale_after: 2027-01-31T00:00:00Z
|
||||
generated: { by: "human:jerome", at: 2026-07-31T00:00:00Z }
|
||||
---
|
||||
|
||||
# IAgent Documentation Rules
|
||||
# Documentation Rules
|
||||
|
||||
## Language
|
||||
## Schema
|
||||
|
||||
All documentation follows the OKF v0.2 specification (see [SPEC.md](https://github.com/wsg-project/wsg/blob/main/docs/rules/SPEC.md)). This document defines project-specific rules for writing and maintaining code documentation.
|
||||
|
||||
## Conventions
|
||||
|
||||
### Language
|
||||
|
||||
All documentation is written in English; as a convention, the code itself uses English for variable names, function names, etc.
|
||||
|
||||
## Code Documentation
|
||||
### Code Documentation
|
||||
|
||||
Every source file and configuration file must be systematically documented following the rules defined in this DOCUMENTATION.md file. Additionally, every directory must contain its own README.md file summarizing and explaining the module's organization at that level: what is the overall responsibility of the files grouped in this directory, which ones they are, and what each one does.
|
||||
|
||||
We assume the reader has professional algorithmic knowledge but may not necessarily be a Rust specialist. The reader does know the project's domain — LLM logic, clients, and agents. Documentation should therefore be tailored for a professional developer who knows some programming languages (not necessarily Rust).
|
||||
|
||||
## Examples
|
||||
|
||||
### General Rule
|
||||
|
||||
Documentation must describe what is coded and what purpose it serves. A LLM reading the code and documentation should be able to verify whether:
|
||||
@@ -29,7 +41,7 @@ Documentation must describe what is coded and what purpose it serves. A LLM read
|
||||
|
||||
Each module or file must include documentation explaining the module's responsibility and how it interacts with other modules in the program, at least those within its own directory. This documentation must detail the main objects (Struct, Enum, Trait) manipulated in the module and the primary functions that carry the module's core logic.
|
||||
|
||||
## Within a File's Code
|
||||
## Internal Steps
|
||||
|
||||
### Object and Function Headers
|
||||
|
||||
@@ -39,6 +51,6 @@ At the header of each object, describe what the object represents and its purpos
|
||||
|
||||
If an object or function presents a particularity or specific technical point, then a descriptive comment is inserted directly into the code body or function body. If a point of attention or technical point was described in the function header, then a comment in the code body reminds where this point is located.
|
||||
|
||||
## Documentation Maintenance
|
||||
## Maintenance
|
||||
|
||||
The rules defined in this file are regularly applied across all code documentation to ensure consistency between code evolution and its documentation.
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user