okf 1.13.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84ee2cefa8e04f2358c9125ca00ccdf9de8a12ab0a78a96315ec846bab8d3e87
-  data.tar.gz: 7a3186c5aa2924b4425a0c0a86c9f0812948427348d4fd3d0cd46852bd6dc575
+  metadata.gz: 43476118366ed4610628f4692f1c1432e4babe4a9d5749f06eb69fc41738c4e5
+  data.tar.gz: 218144bd22483995d933cf9d89f44e9602c2c95255d9e1c95626700a4f5b2f2e
 SHA512:
-  metadata.gz: b0c9f1002b408702c74f73be001eab10b6691419700d33b41e81bd001d21858f1d79289696edbb2ad6e7c6f4a76ccd4c7458cf211e82fded5224f5fcfa6328b4
-  data.tar.gz: 0ed68e0095ab1aa912c5df3b6fd7b9f82e0e07f2cad0c182437cb70021beed8d5ecb054106185204b18d0f138303372bc62202c286aec75ce6c4a43434f2e546
+  metadata.gz: 40ccd9ca9a9fe8580856825a972753b0f58ff2158fec6262db84d0b9d504e24c071a78e5b05939c0c5648ac7da67083621085417547ae194a0343ae1de34694b
+  data.tar.gz: 506f9d1feb6c6428c9db8845b4880207e904901636b35411b8b85f37dc909abb08b96d82246f06e410c97f6991ccfd947a559eed1d9c5b8d8e429b4790bd5929

data/CHANGELOG.md

@@ -5,6 +5,200 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-08-14
+
+> Major, not minor. The Breaking entries below change public shapes a shipped
+> consumer already reads: two lint check ids are renamed, the `stale` finding's
+> JSON metric moves from `timestamp` to `generated_at`, and the `timestamp`
+> catalog column is gone. A v0.1 *bundle* still validates with zero warnings —
+> §13.1's fallbacks hold — but spec compatibility and API compatibility are
+> different promises, and semver tracks the second. okf-mcp's open-ended
+> `okf >= 1.13` is closed to `>= 2.0, < 3` in the same release.
+
+### Added
+
+- **`okf references` — the §6.3 inventory.** Lists every file under
+  `references/`, the non-markdown ones included (the concept model carries
+  only markdown, so no other verb can see a `.py` attester or a `.sql`
+  computation), with which concepts cite each file through the §6.2
+  path-valued fields — plus every pointer into `references/` that resolves to
+  nothing. A bare `references/…` written from a subdirectory resolves relative
+  to the concept (the §6.2 trap the SPEC's own examples invite), and when the
+  leading-slash spelling would have hit, the dangling entry says so. Advisory
+  (exit 0); `--json` with `--fields`/`--except` like the other read views.
+  Backed by `OKF::Bundle::References` (pure) and
+  `OKF::Bundle::Folder#references` (the disk manifest) in the library, and by
+  `Markdown::Links.resolve_path` — `#resolve`'s path arithmetic without its
+  `.md` gate, since §6.2 fields accept any file.
+- **The §5/§10 families across every surface.** The validator warns on their
+  shapes (raw keys only, warnings only — §11's three hard conditions are
+  untouched) and its warnings become machine-readable: each carries `check:`
+  (a stable id) and `source:` (`spec` | `convention`), with errors keeping
+  their exact two-key shape. A root `index.md`'s `okf_version` is actually
+  read now — an unknown version warns under §12 and the bundle is consumed
+  anyway; unquoted `okf_version: 0.2` (a Psych Float) is accepted.
+- **Eight lint categories with pinned severities** (`Linter::SEVERITIES`, a
+  tested constant): Freshness gains `expired` (info, clock-gated — the CLI
+  passes today, `--today YYYY-MM-DD` pins it for reproducible CI reports, and
+  the pure library runs no clock check unless handed `today:`, confessing via
+  `stats[:skipped_checks]`); Provenance gains `broken_source`,
+  `unattributed_claim` (warn — only once a concept adopts keyed attribution,
+  with the label↔id join case-folded the way GFM resolves footnotes),
+  `unused_source`, and `unprefixed_actor` (info — a `verified[].by` outside
+  §7's three forms reads as machine-confirmed); a missing `generated.by` is
+  the validator's warning alone, never double-reported by lint. Attestation
+  gains `incomplete_computation` (warn, on
+  neither-or-both computation shapes) and `broken_attestation_ref` (warn — a
+  `computation`, `executor.resource` or `attester.resource` on an
+  `Attested Computation` naming an in-bundle `.md` that is not there; a contract whose parts are named but
+  absent is one no consumer can follow, so it warns rather than informs, with
+  the same URL/non-`.md` exemption `broken_source` carries); Migration's `legacy_timestamp` and
+  `legacy_citations` (info) name what a v0.1 bundle would change without ever
+  failing it. Reports gain `trust` and `status` distributions.
+- **`--fail-on info`** joins `never | warn` — gateability without a severity
+  promotion; a migration campaign is
+  `okf lint <dir> --only legacy_timestamp,legacy_citations --fail-on info`.
+- **`Linter.call(only:/except:)` refuses an unknown check id** with an
+  ArgumentError naming it, instead of silently intersecting to an empty run
+  that reports healthy — the library-side twin of the CLI's exit 2, and what
+  keeps a caller pinned to a renamed id from reading "checked and fine" over
+  a run that ran nothing.
+- **`--status` and `--trust` filters** on catalog, files, search, tags and
+  types — `--status` matches the effective value (absent reads `stable`),
+  `--trust` folds either tier spelling.
+- **Sources are searchable text** in both Ruby engines (weight 1 — the weight
+  the body text carried in v0.1) and snippet-eligible, so a migrated bundle
+  keeps its recall and a source-only hit keeps a snippet; the static page
+  bakes and indexes the same source text.
+- **Trust as the graph page's third channel**: tier chips, status badges
+  (declared non-default only), a generated line, a client-clock stale marker,
+  and status/trust filter groups counted off the catalog.
+- The skill teaches v0.2: the vendored SPEC is the published v0.2, a new
+  attested-computation template carries §10.3's MUST NOT, and the migrate
+  playbook walks the v0.1→v0.2 rewrite.
+- **`Concept#shows_trust?` and `Bundle::RowFilter.shows_trust?` — §5.3's
+  display half, in one place.** The tier is always derivable; whether a surface
+  should *claim* it is a different question, and the answer is no for a concept
+  that declared no §5 family, which is every concept of every v0.1 bundle.
+  Claiming it there would paint a provenance verdict onto documents that never
+  made one — the false claim the trust system exists to prevent. The rule was
+  spelled twice, inline in `/node/meta` and in the page's `showsTrust`, and a
+  third consumer (okf-tui, which needs it for a chip, a facet gate, the facet
+  counts and the narrowing) is what a hand-copied predicate does not survive:
+  a gate disagreeing with the counts beside it reads "unverified 3" over two
+  chipped cards. One class method takes the two wire values so a Concept and a
+  catalog row ask the same rule; the server now routes through it, and the
+  page's client-side twin — unavoidable, since it runs over baked rows with no
+  Ruby to call — is pinned equal to it by `parity_test.rb`, truth table and
+  source literal both.
+- **`Bundle#okf_version` — the spec version the root index declares (§12)**,
+  as the producer wrote it, or nil when it declares none, which §12 permits.
+  Stringified and stripped for the reason the validator compares that way: an
+  unquoted `okf_version: 0.2` is a Psych Float, and a consumer switching on it
+  must not be handed 0.2 the number. Public because the alternative is a
+  literal — a consumer naming the version on screen had no way to ask, which is
+  how a reader gets told "v0.1" about a bundle declaring 0.2. Unparseable
+  frontmatter stays the validator's error to report rather than this reader's
+  to raise.
+- **`log_order` [info], the first log-side lint check.** §9 describes the log
+  as date-grouped entries, newest first — prose, not an RFC keyword, so
+  disorder is curation slack rather than a conformance error: exactly lint's
+  side of the split. Only shape-valid headings are compared; a malformed date
+  stays the validator's error, reported once.
+- **`unprefixed_actor` now covers `generated.by` too.** §7 gives the actor
+  convention to both identity fields; only `verified[].by` was checked, on the
+  argument that §5.3 derives trust from nothing else — true, but a
+  `generated.by` no form can classify leaves a provenance reader unable to
+  tell a person from a process, so it earns the same info finding with its own
+  consequence. A *missing* `generated.by` stays the validator's warning.
+
+- **`Bundle#stats` and `Bundle#tag_groups` join the library API** —
+  extracted from the CLI's `stats` and `tags --by` so the MCP shell reads
+  the same rollups instead of hand-copying them: the `by_dir` zero-keeping
+  subtlety and the within-group-beside-total tag counting each have one
+  home now (`Folder` delegates both). The CLI verbs are pure consumers of
+  the extraction; their output is unchanged.
+- **Two long-standing behaviors are documented contract now, each with a
+  pinning test.** Hidden files are outside the bundle: the reader excludes
+  dot-prefixed files and everything under a dot-prefixed directory — the
+  Unix convention, kept so reading a project root cannot pull an installed
+  skill or `.github/` templates in as concepts. And a frontmatter `id:`
+  renames the concept, not its home — an extension beyond §2's path-derived
+  identity, with the recorded split stated where authors read it: the
+  identity views (catalog, hubs, `--dir`, search) follow the id, the
+  physical views (`index`, `dirs`, stats' `by_dir`) keep the file where it
+  lives. Both in the skill's authoring guide.
+
+### Changed
+
+- **`validate` warns on a declared-but-blank `status`.** `status: ""` is a
+  producer typo, not an absence — §5.4's default belongs to a concept that
+  never declared the key — and reading the blank through the default turned it
+  into `stable` before the vocabulary check ran, so the one value §5.4 names
+  nowhere was the one that never warned.
+- **`lint --stale-after` refuses the ISO spellings it used to reinterpret.**
+  It took whatever `Date.iso8601` parsed, so the basic (`20260101`) and week
+  (`2026-W01-1`) forms silently became a cutoff nobody asked for — `20260101`
+  read as the year 2026 day 01 of month 01 only by luck of the parser, and
+  `2026-W01-1` as 2025-12-29. Both now exit 2 naming the accepted shapes. A
+  `YYYY-MM-DD` date and a full `2026-01-01T09:00:00Z` timestamp (what a
+  concept's own `generated.at` looks like) are both still accepted, the
+  timestamp reduced to its date as before. The new `--today` takes the
+  narrower grammar — it names a calendar day, not a moment.
+- **The gem targets OKF v0.2** and keeps reading v0.1 under §13.1's two
+  sanctioned fallbacks: a legacy `timestamp` reads as `generated.at` (per-key,
+  so a half-migrated `generated: { by: … }` beside a `timestamp` keeps its
+  date, and no actor is ever invented), and a body `# Citations` list reads as
+  `sources` whenever the native key yields zero mappings. One `OKF::Concept`
+  class, no version hierarchy; a pure v0.1 bundle still validates with zero
+  warnings.
+- **Breaking: lint check ids renamed** — `missing_timestamp` is
+  `missing_generated`, `broken_citation` is `broken_source` — so `--only` /
+  `--except` lists naming the old ids exit 2. `uncited_external` is redefined
+  over `#sources` (a v0.1 `# Citations` still silences it — a prose-only
+  section included; so does a migrated `sources:` block). The `stale`
+  finding's JSON metric renames `timestamp:` to `generated_at:` (and its
+  message says "last updated <generated_at>") — a consumer reading
+  `finding.metric.timestamp` gets `null` and must move with it.
+- **Breaking: the `timestamp` catalog column is removed** — `--fields
+  timestamp` exits 2 loudly, naming the valid fields. The `concepts` row gains
+  `generated_at`, `generated_by`, `generated` (the raw declared-key boolean
+  that tells hand-written apart from v0.1-with-timestamp), `trust` (the
+  hyphenated wire literals `unverified` | `machine-confirmed` |
+  `human-reviewed`), `stale_after`, and a `sources` count. `status` stays the
+  raw declared value, `null` when absent. Temporal values render ISO 8601.
+- **Breaking: `Concept#citations` and `Markdown::Citations.targets` are
+  removed**, both subsumed by `Concept#sources` / `Citations.entries`.
+- **The staleness boundary is `today >= stale_after`** — a concept is stale
+  **on** the day itself, per §5.5. A consumer replacing its own `<`-based
+  check shifts by one day and should know it.
+- `GET /node/meta` returns JSON (`{ description, trust: { tier, generated_by,
+  generated_at, status, stale_after } }`, null-stripped) instead of an escaped
+  HTML fragment; the graph page composes the trust line client-side for served
+  and baked pages alike, and computes expiry against the viewer's own clock.
+- The demo Open Graph card URL the graph template points at moved to
+  `og-demo-v5.png` (the site's card-art version bump); the old URL keeps
+  serving the current art, so nothing breaks in between.
+
+
+### Fixed
+
+- **A calendar-invalid log heading is now a §11 error.** §9's MUST is ISO
+  8601, and `## 2026-02-30` matched the digit shape while naming a day that
+  never existed — the validator now asks `Date.iso8601`, so a log.md is
+  conformant only around real dates.
+- **`MAILTO:` is excluded case-insensitively**, like every other scheme (RFC
+  3986). The guard sat inline and case-sensitive beside the case-insensitive
+  `SCHEME` regex in three places, so an uppercase mailto whose address ends in
+  `.md` resolved as a relative path — a link outside the bundle reported as a
+  file inside it. One `Links::MAILTO` now, beside `SCHEME`, for the same
+  reason `SCHEME` moved there.
+- **`incomplete_computation` requires the fence, not the heading.** §10.3's
+  inline form is a fenced code block under `# Computation`; a heading over
+  prose used to count as provided, and a contract with nothing an executor
+  could run lint'd clean.
+
+
 ## [1.13.0] - 2026-08-07
 
 ### Added
@@ -1322,6 +1516,7 @@ Initial release.
 
 - Runs on Ruby >= 2.4 with two runtime dependencies: rack and webrick.
 
+[2.0.0]: https://github.com/serradura/okf-gem/compare/v1.13.0...v2.0.0
 [1.13.0]: https://github.com/serradura/okf-gem/compare/v1.12.0...v1.13.0
 [1.12.0]: https://github.com/serradura/okf-gem/compare/v1.11.0...v1.12.0
 [1.11.0]: https://github.com/serradura/okf-gem/compare/v1.10.0...v1.11.0

data/README.md

@@ -67,9 +67,10 @@ okf validate  <dir|@slug>                        # is this legal OKF?
 okf lint      <dir|@slug> [--fail-on warn]       # is it navigable, complete, fresh?
 okf loose     <dir|@slug>                        # concepts with no links in or out
 okf search    <dir|@slug…|@all> <term…>          # ranked retrieval; @all spans every bundle
-okf index     <dir|@slug> [--dir D] [--depth N]  # the §6 map: index bodies, rollups, listings
+okf index     <dir|@slug> [--dir D] [--depth N]  # the §8 map: index bodies, rollups, listings
 okf dirs      <dir|@slug> [--dir D] [--depth N]  # the shape: every directory and what it holds
 okf catalog | files | tags | types | stats  <dir|@slug>   # the browser views, on the CLI
+okf references <dir|@slug>                       # the references/ inventory: files, citers, dangling pointers
 okf graph     <dir|@slug> [--hubs] [--traffic]   # the raw graph; --hubs ranks concepts, --traffic dirs
 okf server    [DIR|@slug…] [-p PORT] [--bind ADDR]   # the live graph: one bundle, or all of them
 okf render    <dir|@slug> [-o FILE]              # the same page as one static, self-contained file
@@ -89,7 +90,7 @@ behind one hub. `okf registry init` scopes one to a single project instead, and
 committed `.okf-registry.json` travels with the repo.
 
 **A big bundle is read a level at a time.** `okf index --depth 1 --except
-body,listing` is the map an agent orients on — on a 400-concept bundle, 2.8 KB
+body,listing` is the map an agent orients on — on a 414-concept bundle, 2.8 KB
 against the full 313 KB — and `--dir` then opens one branch, bringing the
 ancestors that say what it is.
 
@@ -105,7 +106,7 @@ require "okf"
 
 folder = OKF::Bundle::Folder.load("docs")
 folder.concepts                  # => [OKF::Concept]
-folder.validate                  # => §9 conformance result
+folder.validate                  # => §11 conformance result
 folder.lint                      # => curation report
 folder.graph                     # => nodes, edges, indexes
 
@@ -122,18 +123,36 @@ writer, and the lower-level pieces.
 ## validate and lint are two different questions
 
 `validate` asks *"is this legal OKF?"* and implements the spec's
-[§9](lib/okf/skill/reference/SPEC.md#9-conformance) exactly — which means it is *forbidden* to
+[§11](lib/okf/skill/reference/SPEC.md#11-conformance) exactly — which means it is *forbidden* to
 reject a bundle for a broken link or a missing optional field.
 
 `lint` asks the complementary question, *"is this well-curated, navigable,
 trustworthy?"*, over exactly those tolerated things: reachability, backlog,
-completeness, freshness, provenance, hygiene. It is advisory and exits `0` even
-with findings unless you pass `--fail-on warn`.
+completeness, freshness, provenance, attestation, migration, hygiene. It is
+advisory and exits `0` even with findings unless you pass `--fail-on warn`, or
+`--only legacy_timestamp,legacy_citations --fail-on info` to gate a migration
+campaign on the two findings that name a bundle's leftover v0.1 spellings and
+nothing else.
 
 Keeping them apart is what lets you gate CI on conformance without gating it on
 taste. `lint --json` is also the structured input an agent reads to reason about
 the two things no checker can compute — contradictions, and *semantic* staleness.
 
+## Trust is data, so you can filter on it
+
+OKF v0.2 lets a bundle say where each concept came from and how far to trust
+it — `generated` (who or what wrote it), `verified` (who confirmed it),
+`status` (its lifecycle), `stale_after` (a declared expiry) — and this gem
+reads the families everywhere: `--status` and `--trust` narrow `catalog`,
+`files`, `search`, `tags` and `types`; the graph page shows each concept's
+tier beside its type; `lint` reports what expired, against a clock you can
+pin (`--today`) for a reproducible report. `okf references` closes the loop
+for §10's attested computations, inventorying the `references/` files —
+attester code, computation files — that back them, with every pointer that
+resolves to nothing named. A v0.1 bundle needs none of this and stays
+readable forever (§13); the two Migration findings tell it what to modernize
+without ever failing it.
+
 ## Extending it
 
 Publish a gem named `okf-*` carrying an `okf/plugin.rb` and installing it is the

data/lib/okf/bundle/folder.rb

@@ -62,6 +62,22 @@ module OKF
         @bundle.directory_index
       end
 
+      def stats
+        @bundle.stats
+      end
+
+      def tag_groups(by:, entries: nil)
+        @bundle.tag_groups(by: by, entries: entries)
+      end
+
+      # The §6.3 inventory — this handle's half is the disk: the reader models
+      # only markdown, so listing `references/` here is how a .py attester or a
+      # .sql computation becomes visible at all. The pure model gets the
+      # manifest and answers the rest (citers, dangling pointers).
+      def references
+        Bundle::References.build(@bundle, files: reference_files)
+      end
+
       # Every log.md with its content, root scope first — read live from disk so a
       # just-appended entry shows without a reload; the reserved snapshot is the
       # fallback if the file has since vanished. Shared by `okf render`'s bake
@@ -119,7 +135,7 @@ module OKF
         Concept::File.new(root: @root, path: path).read
       end
 
-      # Materialize the in-memory bundle to disk (Writer validates §9 before
+      # Materialize the in-memory bundle to disk (Writer validates §11 before
       # publishing, so a malformed bundle is never written).
       def save(overwrite: false)
         Writer.call(
@@ -139,6 +155,16 @@ module OKF
 
       private
 
+      # Bundle-relative paths of every file under references/, sorted. A glob
+      # on a directory that does not exist is simply empty — no references/ and
+      # an empty references/ are the same inventory.
+      def reference_files
+        Dir.glob(File.join(@root, "references", "**", "*"))
+           .select { |path| File.file?(path) }
+           .map { |path| Pathname.new(path).relative_path_from(Pathname.new(@root)).to_s }
+           .sort
+      end
+
       def reserved_hash(basename)
         @bundle.reserved
                .select { |entry| File.basename(entry.path) == basename }

data/lib/okf/bundle/graph.rb

@@ -20,7 +20,7 @@ module OKF
       attr_reader :nodes, :edges, :type_index, :tag_index
 
       def self.build(bundle, minimal: false, body: true)
-        # Best-effort (§9): a malformed concept never reaches here — the reader keeps
+        # Best-effort (§11): a malformed concept never reaches here — the reader keeps
         # it in bundle.unparseable — so the rest of the bundle still renders. Inspect
         # bundle.unparseable to detect skips.
         concepts = bundle.concepts
@@ -51,10 +51,19 @@ module OKF
       # Edges resolve by *path* — a markdown link is a file path — then map that path
       # to the concept living there and use its id, so a frontmatter `id` that differs
       # from the path still lands the edge on the right node.
+      # Body links and sources[].resource entries feed the same resolver: §5.1
+      # says a `resource` naming another concept is a derivation edge that
+      # "already exists in the bundle graph", and this is what makes that true —
+      # it is also what keeps a migrated bundle's graph equal to its v0.1 twin's,
+      # since a `# Citations` in-bundle link stops being a body link the moment
+      # it is lifted into frontmatter. URLs and scope descriptors resolve to
+      # nothing; an unresolvable path is broken_source's to report.
       def self.edges_for(concepts, id_by_path, root)
         seen = Set.new
         concepts.each_with_object([]) do |concept, edges|
-          Markdown::Links.extract(concept.body).each do |raw|
+          targets = Markdown::Links.extract(concept.body) +
+                    concept.sources.map { |source| source["resource"] }.compact
+          targets.each do |raw|
             resolved = Markdown::Links.resolve(raw, from: concept.path, bundle: root)
             next if resolved.nil?
 
@@ -86,7 +95,7 @@ module OKF
         concept.tags.is_a?(Array) ? concept.tags : []
       end
 
-      # Blank, not just nil: §9.2 makes a whitespace-only `type` as non-conformant
+      # Blank, not just nil: §11 condition 2 makes a whitespace-only `type` as non-conformant
       # as a missing one (the validator says so with the same OKF.blank?), so the
       # index must not sort them into different buckets. Otherwise `type: "  "`
       # earns its own row, labelled with spaces, next to Untyped.