okf 1.13.0 → 2.0.0

data/lib/okf/skill/reference/authoring.md

@@ -2,10 +2,10 @@
 
 The spec ([SPEC.md](SPEC.md)) tells you what is *legal*. This file is what is
 *good* — the modelling judgment that turns a pile of conformant files into
-knowledge worth consuming. Read it before `produce` or `maintain`, and keep the §9
-conformance rules in mind (parseable frontmatter, a non-empty `type`, and
-well-formed reserved files — the hard rules in [SKILL.md](../SKILL.md)); everything
-else is guidance a consumer must tolerate.
+knowledge worth consuming. Read it before `produce` or `maintain`, and keep the
+§11 conformance rules in mind (parseable frontmatter, a non-empty `type`, and
+well-formed reserved files — the hard rules in [SKILL.md](../SKILL.md));
+everything else is guidance a consumer must tolerate.
 
 ## What each SPEC section governs
 
@@ -15,12 +15,18 @@ Consult the right section on demand instead of re-reading all of [SPEC.md](SPEC.
 |---|---------|-------------------|
 | §3 | bundle structure, reserved filenames | laying out directories |
 | §4 | concept documents & frontmatter | writing or validating a concept |
-| §5 / §5.3 | cross-links; **broken links are tolerated** | linking; judging a "broken" link |
-| §6 | index files & progressive disclosure | orienting; writing or synthesizing an index |
-| §7 | log files | recording history |
-| §8 | citations & provenance | any external or empirical claim |
-| §9 | conformance — the hard gate | what `validate` may and may not reject |
-| §11 | versioning (`okf_version`) | the root index's one allowed field |
+| §5.1 | provenance — `sources` and its credibility signals | any external or empirical claim |
+| §5.2 / §5.3 | trust — `generated`, `verified`, and the derived tiers | recording who wrote or confirmed content |
+| §5.4 / §5.5 | lifecycle — `status`, `stale_after` | marking drafts, deprecations, expiries |
+| §6 / §6.1 | cross-links; **broken links are tolerated** | linking; judging a "broken" link |
+| §6.2 / §6.3 | path-valued fields; the `references/` convention | pointing at non-concept assets |
+| §7 | the actor convention | filling any `by` |
+| §8 | index files & progressive disclosure | orienting; writing or synthesizing an index |
+| §9 | log files | recording history |
+| §10 | attested computations | a concept that *is* a sanctioned computation |
+| §11 | conformance — the hard gate | what `validate` may and may not reject |
+| §12 | versioning (`okf_version`) | the root index's one allowed field |
+| §13 | changes from v0.1 | migrating a bundle; reading an unmigrated one |
 
 ## Modelling principles
 
@@ -44,7 +50,9 @@ responsibility. Keep a **small, consistent, descriptive** vocabulary per bundle
 (`Service`, `Dataset`, `Metric`, `Decision`, `Playbook`, `Runbook`, …). Reusing
 types across files is what makes the graph legible; inventing a new type per file
 makes `type` meaningless. Before adding a new type, check what the bundle already
-uses.
+uses. One type the spec *does* name: `Attested Computation` (§10) is a contract,
+not a suggestion — use it exactly when the concept carries a sanctioned
+computation, and use the exact spelling.
 
 ### Tags are the connective axis — curate them like a vocabulary <!-- rule:okf-tag-vocabulary -->
 `type` says what a concept *is*; the directory says where it *lives*; `tags` are
@@ -62,15 +70,53 @@ Lay out directories by what the knowledge is *about* (`services/`, `datasets/`,
 `decisions/`), not by concept type. The directory tree is itself knowledge — it
 shows a reader how the system decomposes, and it usually mirrors the shape of the
 codebase or the org. A `types/`-first layout scatters related concepts and buries
-the domain.
+the domain. Non-concept assets a concept points at — run instructions, attester
+code, computation files — live under `references/` by convention (§6.3): a naming
+convention, not a requirement, and the tools never require it.
+
+### Hidden files are outside the bundle <!-- rule:okf-no-hidden-concepts -->
+The reader excludes dot-prefixed files and every path under a dot-prefixed
+directory — the Unix hidden-file convention, kept deliberately: a project root
+often carries an installed skill (`.claude/`), templates (`.github/`) or other
+markdown that is not knowledge, and reading a directory must not pull those in
+as concepts. §3's taxonomy is read as covering the visible tree. The practical
+rule: never author a concept under a hidden directory — no verb will ever see
+it, and nothing will warn you.
+
+### A path-valued field pointing at `references/` needs its leading `/` <!-- check:broken_attestation_ref -->
+§6.2 gives `resource`, `sources[].resource`, `computation`, `executor.resource`
+and `attester.resource` the same three forms as a link: a URL, a bundle-relative
+path **beginning with `/`**, or a path relative to the concept. So a concept at
+`metrics/revenue.md` writing `attester: { resource: references/attesters/rev.py }`
+is naming `metrics/references/attesters/rev.py`, not the bundle's `references/`
+tree — the trap being that §6.3's own example, and the SPEC's Appendix, spell
+these paths bare from a nested concept. Write `/references/…` and the field
+resolves from the bundle root wherever the concept sits, which is the same reason
+[links](#links-are-untyped-on-purpose) prefer the absolute form. `lint` catches
+the `.md` cases (`broken_attestation_ref`, `broken_source`); a `.sql` or `.py`
+target is not a concept, so no lint check sees it — `okf references` is the
+surface that does: it lists the `references/` tree from disk with every pointer
+that misses, and names the leading-`/` fix when that is the miss.
+
+### A frontmatter `id` renames the concept, not its home <!-- rule:okf-id-extension -->
+§2 defines the Concept ID as the file's path with `.md` removed, full stop.
+This gem additionally honors a frontmatter `id:` as an override — an okf
+extension, not spec, so a bundle leaning on it is trading portability for the
+alias. If you pin one, know the recorded split: links still resolve by path,
+so edges land correctly; the identity views (catalog, hubs, search, `--dir`)
+follow the id, because the edges do; the physical views (`index`, `dirs`,
+stats' `by_dir`) keep the file where it lives, because an index is a physical
+listing. A pinned id that disagrees with the path therefore makes the two
+families answer differently about where the concept is — prefer the default,
+and rename the file when a concept needs a new name.
 
 ### `resource` is the bridge to reality <!-- rule:okf-resource-bridge -->
 Set `resource` (a canonical URI) **only** when a concept *is* a real, addressable
 asset — a table (`bigquery://…`), a service repo, a dashboard, an endpoint. Its
 presence is what lets `maintain` find every concept affected by a changed asset in
-one `okf search <dir> <uri>` call. Abstract concepts — a decision, a principle, a metric
-definition — have no resource, and **omitting it is meaningful**, not laziness. Do
-not invent placeholder URIs.
+one `okf search <dir> <uri>` call. Abstract concepts — a decision, a principle, a
+metric definition — have no resource, and **omitting it is meaningful**, not
+laziness. Do not invent placeholder URIs.
 
 ### Links are untyped on purpose <!-- rule:okf-untyped-links -->
 A markdown link asserts only "these two relate." The *kind* of relationship —
@@ -78,15 +124,60 @@ depends-on, supersedes, derived-from, owns — lives in the **prose around the
 link**, never in a made-up typed-edge syntax. Write the sentence that explains the
 relationship and put the link inside it. Prefer absolute bundle-relative targets
 (`/services/auth-api.md`) so links survive file moves. A link to a concept that
-does not exist yet is fine — it is not-yet-written knowledge (§5.3), and `lint`'s
-backlog will surface it as demand.
+does not exist yet is fine — it is not-yet-written knowledge (§6.1), and `lint`'s
+backlog will surface it as demand. One more edge you get for free: a
+`sources[].resource` naming another concept **is** a graph edge (§5.1's lineage),
+so recording provenance is also linking.
 
-### Provenance is what makes knowledge trustworthy (§8) <!-- check:uncited_external -->
+### Provenance lives in `sources`, attribution in footnotes (§5.1) <!-- check:uncited_external -->
 Any external or empirical claim — a latency number, an approval, a quota, a
-"because X team decided Y" — should carry a citation to its source under a
-`# Citations` heading. Uncited claims are exactly how a bundle decays into folklore
-nobody trusts. `lint`'s provenance category exists to catch missing and broken
-citations; write them as you go so you never have to reconstruct them.
+"because X team decided Y" — should be traceable to a `sources:` entry. Each
+entry carries at least a `resource` (a URL, a bundle-relative path, or a scope
+descriptor like `all queries in project X`), and optionally an `id`, `title`,
+and the credibility signals `author` (an actor), `usage_count` (a liveness
+signal, never a score), and `last_modified` (`YYYY-MM-DD`). To attribute a
+*specific claim*, give the source an `id` and cite it with a markdown footnote
+whose label is that id: `sharded daily.[^ga4-schema]` — keyed, not positional,
+so a reordered list cannot misattribute silently. `lint`'s provenance category
+checks the join in both directions (`unattributed_claim`, `unused_source`).
+Uncited claims are exactly how a bundle decays into folklore nobody trusts.
+("Citations" is the legacy v0.1 spelling: provenance lived in a body
+`# Citations` list, which v0.2 retires — §13.1 keeps it readable, and `lint`'s
+Migration findings tell you what to move where.)
+
+### Say who did it, in §7's spelling <!-- check:unprefixed_actor -->
+Every `by` — `generated.by`, `verified[].by` — takes an actor in one of §7's
+three forms: `<producer>/<version>` (an automated producer, e.g.
+`reference_agent/gemini-2.5-pro`), `human:<id>`, or `process:<id>`. The one
+producer MUST: content a person hand-authored **or confirmed** is marked
+`human:<id>` — §5.3 derives the trust tier from exactly this prefix, so a human
+sign-off written `by: owner` silently reads as *machine-confirmed*, the exact
+downgrade the tier system exists to prevent (`lint`'s `unprefixed_actor` nudges
+it). `sources[].author` is looser on purpose: §7 does not govern it, and the
+SPEC's own examples use `team:<id>` there — any honest attribution works.
+
+### Trust is derived, never stored (§5.2/§5.3) <!-- rule:okf-trust-derived -->
+`generated` records how the current content was produced (`by` REQUIRED within;
+`at` an ISO 8601 datetime); `verified` lists who confirmed it against its
+sources — they stay separate because who *wrote* a concept need not be who
+*checked* it. Consumers derive the tier: no `verified` ⇒ unverified; machine
+actors only ⇒ machine-confirmed; any `human:` verifier ⇒ human-reviewed. Never
+write a tier or a credibility score into frontmatter — it would be subjective,
+unportable, and stale the moment the next verification lands. And never invent
+provenance: a concept whose history you do not know is honestly unverified.
+Prefer **block style** for these mappings (`generated:` with indented
+`by:`/`at:`): the flow spelling (`{ by: human:x, at: …T10:00:00Z }`) is legal
+YAML, but the colons inside its values trip older libyaml parsers, and block
+style is the spelling every parser accepts.
+
+### Lifecycle: `status` and `stale_after` (§5.4/§5.5) <!-- rule:okf-lifecycle -->
+`status` is one of `draft | stable | deprecated`; absent means `stable`, so
+declare it only when it says something. `stale_after` is an absolute
+`YYYY-MM-DD` — the author's own "do not trust me past this date", stale **on**
+the day itself. Use it for knowledge with a known shelf life (a quota, a
+migration window); `lint`'s `expired` check reports the ones whose date has
+passed. It is a declared expiry, distinct from the `--stale-after` *flag*,
+which is a reader-supplied age cutoff — see [cli.md](cli.md).
 
 ### Capture the non-obvious — not what code already says <!-- rule:okf-non-obvious -->
 A bundle that restates function signatures or config keys goes stale the moment
@@ -98,19 +189,46 @@ to it rather than duplicating it.
 
 ### Write for both readers at once <!-- rule:okf-dual-audience -->
 Use structural markdown so an agent can extract deterministically and a human can
-skim: headings, tables, fenced code, lists. Conventional headings a reader expects
-are `# Schema` (field/column tables), `# Examples`, and `# Citations`. Fill
-recommended frontmatter — `title`, `description`, `tags`, `timestamp` (ISO 8601) —
-whenever it aids consumption.
+skim: headings, tables, fenced code, lists. Conventional headings a reader
+expects are `# Schema` (field/column tables), `# Examples`, and — on an Attested
+Computation only — `# Computation` (§10.3). Fill recommended frontmatter —
+`title`, `description`, `tags`, `generated` — whenever it aids consumption.
+
+### Attested computations are contracts (§10) <!-- rule:okf-computation-untouched -->
+A concept of type `Attested Computation` carries a sanctioned computation:
+`runtime` is REQUIRED (it fixes what `parameters` mean), the computation is
+provided **exactly one way** — a body `# Computation` fence *or* a
+`computation:` path, never both — and `executor`/`attester` name how it runs
+and how a run is checked. The one new MUST NOT in v0.2 binds the *consumer*: an
+agent MAY bind values for the declared `parameters` and MUST NOT author or edit
+the computation itself. A "fixed" query silently stops being the one a person
+sanctioned; if it is wrong, tell a human. The
+[attested-computation template](../templates/attested-computation.md) carries
+the whole contract.
 
 ### Reserved files <!-- rule:okf-reserved-files -->
 `index.md` is a directory listing and carries **no frontmatter** — with one
 exception: the **bundle-root** `index.md` is the only index that may carry
-frontmatter, and it may carry *only* `okf_version: "0.1"` (§11; `validate` §9.3
-flags any other key there). `log.md` is an ISO-dated change history, newest first.
-Never use these names for concepts. Templates:
-[concept](../templates/concept.md), nested [index](../templates/index.md),
-bundle-root [root-index](../templates/root-index.md), [log](../templates/log.md).
+frontmatter, and it may carry *only* `okf_version: "0.2"` (§8 states the
+exception inline; `validate` flags any other key there under §11 condition 3).
+`log.md` is an ISO-dated change history, newest first. Never use these names for
+concepts. Templates: [concept](../templates/concept.md),
+[attested computation](../templates/attested-computation.md),
+nested [index](../templates/index.md), bundle-root
+[root-index](../templates/root-index.md), [log](../templates/log.md).
+
+## Migrating from v0.1 (§13)
+
+A v0.1 bundle is consumable forever — §13.1 sanctions reading `timestamp` as
+`generated.at` and a `# Citations` list as `sources` — so migration is
+convenience, not rescue. Exactly two spellings retire: `timestamp` (move the
+value under `generated: { by: <actor>, at: … }` — the actor is the one thing no
+tool can derive; ask, or write `human:<maintainer>` when the history is human)
+and the body `# Citations` section (lift each item into `sources`, add `id`s
+and `[^id]` footnotes where the body cites, delete the section). `lint`'s two
+Migration findings name the files; the [migrate playbook](../playbooks/migrate.md)
+walks the rewrite, and `okf lint <dir> --only legacy_timestamp,legacy_citations
+--fail-on info` is the mechanical done-check.
 
 ## Playbooks
 
@@ -130,9 +248,10 @@ grep can't:
   removed is updated; re-run `okf index` and eyeball each listing against reality.
   Easy to skip, expensive to miss — this is the check that was missing.
 - **`log.md`** — a dated entry, newest first.
-- **Timestamps** bumped on the concepts you touched.
-- **`validate`** — zero §9 errors.
-- **`lint`** — cheap findings cleared; pass `--stale-after` when concepts carry
-  timestamps (freshness is off by default).
+- **`generated.at`** bumped on the concepts you touched (and `generated.by` says
+  who touched them — you, in §7's spelling).
+- **`validate`** — zero §11 errors.
+- **`lint`** — cheap findings cleared; `expired` reports out of the box, and
+  `--stale-after` adds the reader-side age cutoff when you want one.
 - **`loose` review + tag curation** — the two semantic passes (maintain steps 6–7);
   worth a pass in `produce` too on a non-trivial bundle.

data/lib/okf/skill/reference/cli.md

@@ -65,7 +65,7 @@ or `okf index @` work from any directory, no path recall needed.
 
 **Exit codes:** `0` success · `1` non-conformant bundle (or a `lint --fail-on`
 threshold crossed) · `2` usage error. `graph`, `server`, and `render` are best-effort
-(§9): a file the reader cannot use — frontmatter that will not parse, or a file it
+(§11): a file the reader cannot use — frontmatter that will not parse, or a file it
 cannot open at all — is skipped and noted on stderr, never fatal. The note counts;
 `validate` names each file and why.
 
@@ -74,43 +74,95 @@ cannot open at all — is skipped and noted on stderr, never fatal. The note cou
 or a mix — and it is a usage error (exit 2), never a silent answer about the first.
 To ask the same question of several bundles, ask `search`, or ask each in turn.
 
-## validate — the hard gate (§9)
+## validate — the hard gate (§11)
 
-Implements the spec's §9 conformance definition exactly:
+Implements the spec's §11 conformance definition exactly:
 
-- **§9.1** every non-reserved file has a parseable YAML frontmatter block;
-- **§9.2** every such block has a non-empty `type`;
-- **§9.3** any `index.md`/`log.md` present follows §6/§7 (a nested `index.md` has
-  no frontmatter, a root `index.md` carries only `okf_version`, `log.md` date
-  headings are ISO `YYYY-MM-DD`).
+- **§11 cond. 1** every non-reserved file has a parseable YAML frontmatter block;
+- **§11 cond. 2** every such block has a non-empty `type`;
+- **§11 cond. 3** any `index.md`/`log.md` present follows §8/§9 (a nested
+  `index.md` has no frontmatter, a root `index.md` carries only `okf_version`,
+  `log.md` date headings are ISO `YYYY-MM-DD`).
 
 `ERROR`s are the three conditions above; the bundle is non-conformant until every
 one is fixed. `warn`s are soft — missing recommended fields, non-list tags, an
-unparseable timestamp, and **broken cross-links, which §5.3 explicitly tolerates**.
-Fix warnings when cheap; never block on them. Use `--json` in CI.
+unparseable timestamp, **broken cross-links, which §6.1 explicitly tolerates**,
+the shape of every §5/§10 family (`generated` not a mapping, a non-integer
+`usage_count`, a `stale_after` that is not `YYYY-MM-DD`, a missing `runtime` on
+an Attested Computation, …), and an `okf_version` the gem does not know (read
+best-effort under §12; an absent one never warns). Absence of an optional family
+is never a fault — a pure v0.1 bundle validates with zero warnings.
+
+In `--json`, every warning carries `check` (a stable id) and `source` — `spec`
+when the SPEC's own words state the rule, `convention` for a shape this gem asks
+for beyond them (`verified[].by` presence, integer `usage_count`, a per-entry
+`usage_window` mapping, `parameters[].name`, `executor`/`attester` `resource`).
+Gate on `source` when you want only the spec-normative set; errors keep their
+two-key `{ path, message }` shape. Fix warnings when cheap; never block on them.
+Use `--json` in CI.
 
 ## lint — curation quality (advisory)
 
 Asks the complementary question to `validate`: not "is this legal OKF?" but "is
-this well-curated, navigable, trustworthy?" — precisely over the things §9 forbids
-`validate` from rejecting. It has its own report, never emits conformance errors,
-and **exits `0` even with findings** unless you pass `--fail-on warn`.
-
-Six conceptual categories, each backed by individual checks (names in parens):
-
-- **reachability** — orphans, concepts not in any index, disconnected islands,
-  and unlinked (degree-0) files
-  (`orphan`, `not_in_index`, `disconnected_component`, `unlinked`)
-- **backlog** — demand-ranked missing concepts (linked-to but absent), broken index entries
-  (`missing_concept`, `broken_index_entry`)
-- **completeness** — stubs, missing `title` / `description` / `timestamp`
-  (`stub`, `missing_title`, `missing_description`, `missing_timestamp`)
-- **freshness** — concepts older than a cutoff (`stale`) — **only computed when you
-  pass `--stale-after`; a plain `okf lint` never reports staleness at all**
-- **provenance** — uncited external claims, broken citations, spec §8
-  (`uncited_external`, `broken_citation`)
-- **hygiene** — duplicate titles, unused/undefined reference links, self-links
-  (`duplicate_title`, `unused_reference_def`, `undefined_reference`, `self_link`)
+this well-curated, navigable, trustworthy?" — precisely over the things §11
+forbids `validate` from rejecting. It has its own report, never emits
+conformance errors, and **exits `0` even with findings** unless you pass
+`--fail-on warn` (exit 1 on any `warn` finding) or `--fail-on info` (exit 1 on
+any finding at all).
+
+**Severity is API.** Every check has a pinned level — `warn` or `info` — and
+machine consumers gate on it, so the levels below are stable, not advisory. A
+finding you want to gate on that is `info` gets `--fail-on info` (usually with
+`--only`), never a hope that its severity changes.
+
+Eight categories, each backed by individual checks (severity in brackets):
+
+- **Reachability** — `orphan` [warn], `not_in_index` [warn],
+  `disconnected_component` [info], `unlinked` [info]
+- **Backlog** — `missing_concept` [info], `broken_index_entry` [warn]
+- **Completeness** — `stub` [info], `missing_title` [info],
+  `missing_description` [info], `missing_generated` [info] (quiet on either
+  spelling — a legacy `timestamp` still counts as a recorded change)
+- **Freshness** — `expired` [info] (§5.5: past the concept's own declared
+  `stale_after`, on the day itself), `stale` [warn] (older than the
+  reader-supplied `--stale-after` cutoff, keyed on `generated_at`)
+- **Provenance** — `uncited_external` [info] (external body links and no
+  sources, in either spelling), `broken_source` [warn] (an in-bundle `.md`
+  source target that names no concept; URLs and scope descriptors are out of
+  scope, and a non-`.md` asset is out of reach — the reader models concepts,
+  so lint never sees the file; `okf references` is the view that checks those
+  pointers), `unattributed_claim` [warn] (a footnote
+  no `sources[].id` answers — it *misattributes* a claim, which is why it
+  outranks its join-twin), `unused_source` [info] (a keyed source no footnote
+  cites — slack, not a defect), `unprefixed_actor` [info] (a `verified[].by`
+  outside §7's three forms reads as machine-confirmed; a `generated.by`
+  outside them feeds no tier but leaves a reader unable to tell a person
+  from a process; info so it informs, never blocks). A missing `generated.by` is the *validator's* warning —
+  REQUIRED-within is shape, not curation — so lint never double-reports it
+- **Attestation** — `incomplete_computation` [warn] (an Attested Computation
+  providing its computation neither way, or both ways — §10.3 says a
+  `computation:` path is used *instead of* the body fence),
+  `broken_attestation_ref` [warn] (on an `Attested Computation`, a
+  `computation`, `executor.resource` or `attester.resource` naming an
+  in-bundle `.md` that is not there — a contract no consumer can follow; the
+  keys are read only on that type, since §4.1 lets any other concept use them
+  for its own purpose). Its reach is exactly the `.md` files: URLs are out
+  of scope, and a `.sql` or `.py` target is invisible to *every* check here,
+  because the linter reads the concept model and the model carries only
+  markdown — `okf references` is the surface that sees those files and reports
+  a pointer that misses, whatever the extension. Remember §6.2 reads a bare
+  `references/…` as relative to the concept, so from a nested concept it wants
+  the leading `/`
+- **Migration** — `legacy_timestamp` [info], `legacy_citations` [info]: one
+  finding per bundle naming the files still in a retired v0.1 spelling, with
+  the rewrite instructions in the message. Info on purpose — §13 says a v0.1
+  bundle is consumable forever, so `--fail-on warn` must not turn red on one.
+  A migration campaign gates explicitly:
+  `okf lint <dir> --only legacy_timestamp,legacy_citations --fail-on info`,
+  exit 1 until clean.
+- **Hygiene** — `duplicate_title` [info], `unused_reference_def` [info],
+  `undefined_reference` [warn], `self_link` [info], `log_order` [info] (§9
+  reads a log newest-first; disorder is slack, never a §11 error)
 
 `--only` / `--except` filter by the **individual check names above**, not the
 category labels — `okf lint <dir> --only orphan,stub` works; `--only reachability`
@@ -119,6 +171,26 @@ threshold in characters (default 50), and `--stale-after DUR` sets the `stale`
 cutoff — a duration like `90d` or `12w`, or an ISO date like `2026-01-01` (a bare
 number is rejected).
 
+**Two different clocks, one unlucky name.** The `--stale-after` *flag* and the
+`stale_after:` *frontmatter field* are different mechanisms that happen to share
+a spelling. The flag is the **reader's** age cutoff: "flag anything not touched
+since DUR", keyed on `generated_at`, feeding the `stale` check. The field is the
+**author's** declared expiry: "do not trust this past DATE", feeding the
+`expired` check. Never read one as the other, and never show them adjacent
+without the distinction.
+
+**The clock is explicit.** `expired` compares against a day the CLI supplies —
+today by default, or `--today YYYY-MM-DD` for a reproducible report (CI wants
+this). The pure library runs no clock check unless handed `today:`, and every
+clock-gated check that was selected but could not run is *named* in
+`stats.skipped_checks` (the human report prints one `skipped:` line) — a gate
+that is sometimes absent and does not confess converts "unchecked" into
+"checked and fine".
+
+The report's stats carry the bundle's posture too: `trust` (the §5.3 tier
+distribution, in the hyphenated wire spelling) and `status` (effective-status
+frequency).
+
 `lint --json` is the structured substrate you consume to reason about the two
 things lint deliberately does **not** compute — contradictions and *semantic*
 staleness — which need understanding of meaning.
@@ -150,8 +222,10 @@ as Ruby regular expressions with `--regexp`/`-e` (an invalid pattern is a usage
 error, exit 2). `--fuzzy` forgives typos; pairing it with `-e` is a usage error,
 since a pattern is matched literally rather than by edit distance.
 `--in a,b` restricts the searched fields (title, id, tags, type, description,
-body); the shared `--type/--dir/--tag` filters narrow the candidates *first*,
-so a search scoped by what `index` taught you stays surgical.
+sources, body — `sources` is each entry's title and resource joined, so a
+migrated bundle keeps the recall its `# Citations` body text used to give it);
+the shared `--type/--dir/--tag/--status/--trust` filters narrow the candidates
+*first*, so a search scoped by what `index` taught you stays surgical.
 
 **The default is exact, so an exact query means what it looks like.** A phrase in
 one argument (`"dedup key"`), a dotted version (`7.2.0`), an underscored
@@ -261,7 +335,7 @@ same-id concepts from different bundles become indistinguishable. The retrieval
 map first, finder second, bodies last — is the
 [search playbook](../playbooks/search.md).
 
-## index — the progressive-disclosure map (§6)
+## index — the progressive-disclosure map (§8)
 
 The "orient before you read" view, and the read verb that sees the layer the
 concept views can't: `index.md` files are reserved/structural, so
@@ -300,7 +374,7 @@ and `--except body,listing` on top of either is the lean JSON skeleton. Full
 `--no-body` drops the prose to a
 skeleton (headers, rollups, child pointers). For a directory that has concepts but
 **no `index.md`**, the listing is **synthesized** from the concepts' descriptions
-and tagged `(no index.md)` — §6 explicitly permits synthesizing a map on the fly.
+and tagged `(no index.md)` — §8 explicitly permits synthesizing a map on the fly.
 
 It is a **read view**: advisory, always exit 0. A synthesized directory is a
 *signal* (a map worth writing), never a defect — `index` emits no lint findings and
@@ -357,11 +431,22 @@ verbs reproduce them on the CLI so an agent can read a bundle without a browser.
 All are advisory reads (exit 0) sharing one data source (per-concept metadata plus
 in/out link degree). Add `--json` to any for a machine substrate.
 
-- **`catalog`** — every concept with its metadata (type, status, tags, timestamp,
-  in/out link degree, description), grouped by top-level dir (`dir` on every row
-  carries the full path, `top_dir` the first segment). The "what's here, in
-  detail" view. JSON: `{ bundle, count, concepts: [{ id, title, type, description,
-  tags, timestamp, status, backlog_ref, dir, top_dir, links_out, links_in }] }`.
+- **`catalog`** — every concept with its metadata (type, status, trust, tags,
+  provenance, in/out link degree, description), grouped by top-level dir (`dir`
+  on every row carries the full path, `top_dir` the first segment). The "what's
+  here, in detail" view. JSON: `{ bundle, count, concepts: [{ id, title, type,
+  description, tags, generated_at, generated_by, generated, trust, status,
+  stale_after, sources, backlog_ref, dir, top_dir, links_out, links_in }] }`.
+  Four of those deserve a sentence: `generated` is the raw boolean ("does the
+  document *declare* a generated mapping"), which is what tells hand-written
+  apart from v0.1-with-timestamp — `generated_at` alone conflates them, because
+  §13.1 lifts a legacy `timestamp` into it. `trust` is the derived §5.3 tier as
+  a hyphenated literal (`unverified` | `machine-confirmed` | `human-reviewed`) —
+  compare against exactly those. `status` is the *declared* value, `null` when
+  absent (the row never fabricates frontmatter; the `--status` filter is what
+  applies the §5.4 default). `sources` is a count. Temporal fields render
+  ISO 8601 (`stale_after` as `YYYY-MM-DD`). The `timestamp` column is retired —
+  `--fields timestamp` is a usage error naming the valid fields.
 - **`files`** — the folder tree: each concept's filename + title, grouped by
   directory. The "how it's organised" view. JSON: `{ bundle, count, files: [{ path,
   id, dir, type, title, description }] }`.
@@ -389,8 +474,14 @@ in/out link degree). Add `--json` to any for a machine substrate.
   can address.
 
 The four list views narrow with the same filters the browser panels offer —
-`--type TYPE`, `--dir PATH`, `--tag TAG`; each takes the ones orthogonal to
-itself (`tags` can't filter by tag). Matching is case-insensitive; `--type` and
+`--type TYPE`, `--dir PATH`, `--tag TAG`, `--status STATUS`, `--trust TIER`
+(`search` takes them too); each takes the ones orthogonal to itself (`tags`
+can't filter by tag). `--status` matches the *effective* status (absent reads
+`stable`, §5.4) and `--trust` the derived tier, either spelling
+(`machine-confirmed` or `machine_confirmed`) — on a v0.1 bundle
+`--status stable` and `--trust unverified` match everything, which is §13.1
+reading, not an error, and an unknown value matches nothing at exit 0.
+Matching is case-insensitive; `--type` and
 `--tag` are exact, `--dir` takes the named directory **and everything below it**
 (`--dir platform` reaches `platform/services/api`). A concept at the bundle root
 lives in `.`, which `--dir` also accepts as plain `root` (no shell quoting) —
@@ -411,6 +502,28 @@ plus whatever the other flag selected: an answer to neither question.
 Reach for `stats` first to size a bundle, `catalog`/`files` to enumerate it, `tags`
 to find thematic clusters — all without standing up the server.
 
+## references — the `references/` inventory (§6.3)
+
+Lists every file under `references/` — including the non-markdown ones no other
+verb can see, since the concept model carries only markdown — with which
+concepts cite each file through the §6.2 path-valued fields (`resource`,
+`sources[].resource`, `computation`, `executor.resource`, `attester.resource`),
+plus every pointer into `references/` that resolves to nothing. Advisory:
+**exits `0`** even with dangling pointers — the findings are the output. JSON:
+`{ bundle, dangling, count, references: [{ path, dir, kind, referenced_by }] }`,
+with `--fields`/`--except` projecting the rows. A file that is itself a concept
+(§6.3 allows both) is marked `kind: "concept"`; body links are the graph's
+business and are not counted here.
+
+**The dangling list is where §6.2's bare-path trap surfaces.** A bare
+`references/attesters/rev.py` written from `metrics/` resolves relative to the
+concept — `metrics/references/attesters/rev.py`, nothing — and when the
+leading-slash spelling would have hit, the entry says so:
+`/references/attesters/rev.py exists — missing leading slash?`. Reach is any
+extension, which is exactly what `broken_source` and `broken_attestation_ref`
+cannot offer (their exemptions above), so run it wherever a bundle carries
+attester code or computation files.
+
 ## server — interactive graph server
 
 Starts a local HTTP server (`okf server <dir>`; `-p`/`--port`, default 8808, and
@@ -429,7 +542,7 @@ select — depth 1 is the flat view, and a flat bundle is offered no control. Th
 UI too: the Files view carries **Files | Indexes** tabs — the Indexes tab
 lists the log first (the chronological index), then every `index.md` — and
 folder nodes in file-tree mode and directory boxes in cluster mode open a
-directory's §6 map in the inspector (authored, or synthesized when none
+directory's §8 map in the inspector (authored, or synthesized when none
 exists). Links to an `index.md`, `log.md`, or bare directory navigate instead
 of dead-ending, and the log is fetched fresh on every read, so a
 just-appended entry shows without a restart. `?view=index` jumps straight to
@@ -552,7 +665,7 @@ Prints the node/edge graph. `--json` emits a machine-readable dump — the
 `id`/`type`/`title`/`description`/`tags` **and, by default, every `body`** — the
 part that dominates the bytes on a real bundle) plus `edges` — you can pipe into
 other analysis. A concept with a missing *or blank* `type` indexes under
-`Untyped`: §9.2 rejects both identically, so both land in one bucket. To *plan* a traversal, structure is all you need: `--no-body`
+`Untyped`: §11 condition 2 rejects both identically, so both land in one bucket. To *plan* a traversal, structure is all you need: `--no-body`
 drops each node's body, and `--minimal` ships only `id`/`title` plus the type/tag
 indexes — the lean shape the `server` page boots from. Reach for the full dump
 only when the task truly consumes every body; for one question, the

data/lib/okf/skill/templates/attested-computation.md

@@ -0,0 +1,41 @@
+---
+type: Attested Computation
+title: <What the computation answers, e.g. Revenue for fiscal year>
+description: <Single sentence: what this computes and per whose definition.>
+tags: [<tag>]
+runtime: <REQUIRED — what runs it and what parameters mean: bigquery, dbt, python, …>
+parameters:
+  - { name: <name>, type: <type>, required: true }
+executor:
+  resource: <path to run instructions, e.g. /references/skills/run-on-bq.md>
+  receipt: [<field>, <field>]
+attester:
+  resource: <path to the deterministic check, e.g. /references/attesters/check.py>
+generated:
+  by: <actor per §7>
+  at: <ISO 8601>
+sources:
+  - id: <stable-key>
+    title: <the definition this computation implements>
+    resource: <url or path>
+---
+
+# Computation
+
+<The sanctioned computation, in one fenced block — OR set `computation: <path>`
+in the frontmatter instead and omit this section entirely (§10.3: a path is
+used *instead of* the fence; providing both leaves a consumer two candidate
+computations and no rule for which was sanctioned).>
+
+```<language>
+<the computation>
+```
+
+<Prose around it may cite sources per claim.[^<stable-key>]>
+
+<!-- rule:okf-computation-untouched -->
+<!-- §10.3, v0.2's only new MUST NOT: an agent MAY bind values for the declared
+     `parameters` and MUST NOT author or edit the computation itself. The whole
+     point of the type is that the computation is sanctioned — reviewed by a
+     person — and an improvised or "fixed" query silently loses that status.
+     If the computation is wrong, say so to a human; do not repair it. -->

data/lib/okf/skill/templates/concept.md

@@ -4,12 +4,23 @@ title: <Human-readable display name>
 description: <Single sentence summarizing the concept.>
 resource: <Canonical URI of the underlying asset — omit for abstract concepts>
 tags: [<tag>, <tag>]
-timestamp: <ISO 8601, e.g. 2026-06-14T10:00:00Z>
+generated:
+  by: <actor per §7 — human:<id>, process:<id>, or <producer>/<version>>
+  at: <ISO 8601, e.g. 2026-06-14T10:00:00Z>
+sources:
+  - id: <stable-key-the-body-cites>
+    title: <source title>
+    resource: <url, bundle-relative path, or scope descriptor>
+# Optional §5 families, when they apply:
+#   verified: [{ by: <actor>, at: <ISO 8601> }]   — who confirmed the content (a bare mapping reads as a one-element list)
+#   status: draft | stable | deprecated            — absent means stable
+#   stale_after: YYYY-MM-DD                        — stale on the day itself
 ---
 
 # Overview
 
-<What this concept is and why it matters.>
+<What this concept is and why it matters. Attribute each empirical claim to a
+source by its id: "The events table is sharded daily.[^<stable-key-the-body-cites>]">
 
 # Schema
 
@@ -18,7 +29,3 @@ timestamp: <ISO 8601, e.g. 2026-06-14T10:00:00Z>
 | Field | Type | Description |
 |-------|------|-------------|
 |       |      |             |
-
-# Citations
-
-[1] [<source title>](<url>)

data/lib/okf/skill/templates/root-index.md

@@ -1,5 +1,5 @@
 ---
-okf_version: "0.1"
+okf_version: "0.2"
 ---
 
 # <Directory / Group Heading>

data/lib/okf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OKF
-  VERSION = "1.13.0"
+  VERSION = "2.0.0"
 end