okfrules

README

okfrules

The invariants every OKF bundle in this fleet keeps and the spec deliberately does not. §11 forbids rejecting a bundle over an unknown type, a missing key or a broken link, so a local vocabulary is only a rule while something asserts it — two bundles drifted before anything did.

okf.MainWith(os.Args[1:], os.Stderr, okfrules.Standard())

Rule	Refuses
ResourceResolves	a resource: naming a path that is gone
TypeVocabulary	a type outside the skills' table
VerifiedWellFormed	a verified: stamp not naming a human:, or older than generated.at
StaleAfterHasAReason	a stale_after with no sources: naming what expires
IndexHeadingsAreSingularTypes	## Decisions where the table says Decision
LogFrontmatter	a log.md missing type: Log or its title
NoIntraBundleWikilinks	[[name]] inside a bundle — link with markdown, or name the home
LogVerbs	a log entry led by something outside the four verbs

Standard() is the first six: measured over all ten fleet bundles they fire twice in total, and both are real. Strict() adds the last two, which need a conversion first — 82 wikilinks in one bundle, and two logs writing a bold summary where the vocabulary wants a verb. A rule that lands sixty reds on the commit that turns it on is a bulk edit, not a gate, so a repo takes those on the commit that finishes converting.

Everything is okf.Error. These are not the spec's advisory half: each one says a concept is describing something that is not there, or is filed where nothing will find it.

Documentation

Overview

Package okfrules holds the invariants every bundle in this fleet keeps but the OKF spec deliberately does not: §11 forbids rejecting a bundle over an unknown type, a missing key or a broken link, so a local vocabulary is only a rule while something asserts it. Two bundles drifted before anything did.

Index

• Variables
• func IndexHeadingsAreSingularTypes(types []string) okf.BundleRule
• func LogFrontmatter(b okf.Bundle) []okf.Finding
• func LogVerbs(verbs []string) okf.BundleRule
• func NoIntraBundleWikilinks(b okf.Bundle) []okf.Finding
• func ResourceResolves(d okf.Doc) []okf.Finding
• func StaleAfterHasAReason(d okf.Doc) []okf.Finding
• func Standard() okf.Rules
• func Strict() okf.Rules
• func TypeVocabulary(types []string) okf.Rule
• func VerifiedWellFormed(d okf.Doc) []okf.Finding

Variables

var (
	DefaultTypes = []string{
		"Decision", "Component", "Interface", "Constraint", "Policy", "Runbook",
		"Skill", "Glossary Term", "Attested Computation", "Scenario", "Defect",
	}
	DefaultLogVerbs = []string{"Creation", "Update", "Deprecation", "Remove", "Verified"}
)

The vocabularies the okf-knowledge-bundle and okf-bootstrap skills tabulate.

Functions

func IndexHeadingsAreSingularTypes

func IndexHeadingsAreSingularTypes(types []string) okf.BundleRule

IndexHeadingsAreSingularTypes keeps the index's groups joinable across bundles. The level is free — an index may open with a title and an orienting paragraph — but "Decisions" is a group nothing else can join.

func LogFrontmatter

func LogFrontmatter(b okf.Bundle) []okf.Finding

LogFrontmatter: `title` is what the bootstrap template prescribes and what the two newest bundles dropped. Nothing noticed, because nothing looked.

func LogVerbs

func LogVerbs(verbs []string) okf.BundleRule

LogVerbs holds the log to its four verbs. The log is the bundle's history and a free-text verb makes it unreadable as a series.

func NoIntraBundleWikilinks

func NoIntraBundleWikilinks(b okf.Bundle) []okf.Finding

NoIntraBundleWikilinks refuses `[[name]]` inside a bundle. OKF's graph is ordinary markdown links, which okf resolves and reports on; a wikilink is invisible to it, so a target that stops existing goes quiet instead of warning. A reference into another home keeps the syntax with its home named — `[[memory:some-note]]` — which is the half no checker running in CI can resolve anyway.

func ResourceResolves

func ResourceResolves(d okf.Doc) []okf.Finding

ResourceResolves refuses a concept whose `resource:` names a path that is gone. A concept describing something that no longer exists is the one kind of rot a checker can prove, and the fix is always cheaper than the bypass: repoint it, mark the concept deprecated, or drop the key, which is optional.

func StaleAfterHasAReason

func StaleAfterHasAReason(d okf.Doc) []okf.Finding

StaleAfterHasAReason keeps the date for genuine shelf life — a vendor EOL, a certificate — by requiring the external thing that expires to be named. A date set because a concept felt old is a re-verification treadmill nobody asked for, and two of 242 concepts carry one at all.

func Standard

func Standard() okf.Rules

Standard is what a bundle can adopt today without a bulk edit first. Measured over all ten fleet bundles, these fire twice in total, and both are real. A repo with a local rule appends to the returned lists rather than rebuilding them.

func Strict

func Strict() okf.Rules

Strict adds the two rules that demand a conversion before they can be adopted: wikilinks number 82 in one bundle alone, and two logs write a bold summary where the vocabulary wants a verb — roughly 60 firings between them. A rule that lands 60 reds on the commit that turns it on is a bulk edit, not a gate, so a repo takes these on the commit that finishes the conversion.

func TypeVocabulary

func TypeVocabulary(types []string) okf.Rule

TypeVocabulary refuses a `type` outside the fleet's table. `type: Constraints` is the drift this catches: a group nothing joins up across bundles.

func VerifiedWellFormed

func VerifiedWellFormed(d okf.Doc) []okf.Finding

VerifiedWellFormed refuses a stamp an agent could have written. v0.2 splits provenance from trust: `generated:` says who wrote a concept and `verified:` who confirmed it, so a stamp naming a model, or naming nobody, is the whole key defeated.