okf 1.12.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a83101e62e3b3bc97d7351580d50ecc017be391a5edbde2e8f52388de529111
-  data.tar.gz: 040be5295642da56cbeed342424872469d1c2b15efcb1b477f10076d7c90fafc
+  metadata.gz: 43476118366ed4610628f4692f1c1432e4babe4a9d5749f06eb69fc41738c4e5
+  data.tar.gz: 218144bd22483995d933cf9d89f44e9602c2c95255d9e1c95626700a4f5b2f2e
 SHA512:
-  metadata.gz: 47fb84d8dffc04eee30eb65adfaca756ae43315e2d152e62692084a5bd04c6a7992529d243b2375412a8339a55db891c3ae18d679e171d5709e9426b93686047
-  data.tar.gz: 30390e1eecc1570b28531c374b21200309630aad87f821a7c3f25b631ca5285e03b91baab9048f69127931a09368da1ab38a089fc9bc25473c05da3c0fadfe2b
+  metadata.gz: 40ccd9ca9a9fe8580856825a972753b0f58ff2158fec6262db84d0b9d504e24c071a78e5b05939c0c5648ac7da67083621085417547ae194a0343ae1de34694b
+  data.tar.gz: 506f9d1feb6c6428c9db8845b4880207e904901636b35411b8b85f37dc909abb08b96d82246f06e410c97f6991ccfd947a559eed1d9c5b8d8e429b4790bd5929

data/CHANGELOG.md

@@ -5,6 +5,299 @@ 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
+
+- **`Bundle#directories`** — the bundle's own answer to "does this bundle have
+  directory X?", public because every surface now asks it (the CLI's concept
+  views, `okf-mcp`'s `dir` refusal) and the API this version's minor bump
+  exists for. Introduced by, and argued in, the `root` fix under Fixed below.
+
+### Changed
+
+- **The repository became a monorepo, and the gem moved into `okf/`.** Nothing
+  about the published gem changes in kind — same name, same library, same `v*` tag
+  series, same image, byte-identical in size to a pre-move build — but a checkout is laid out differently: one
+  directory per gem, named for the gem it ships, so `okf-mcp/` and the rest can
+  land beside the baseline without reshaping anything. `plugin/`,
+  `.claude-plugin/`, `.okf/` and the `Dockerfile` stay at the root; the last of
+  those because its build context must be the repo root, where the `.git` the
+  gemspec's `git ls-files` needs lives. From a checkout it is `cd okf` for
+  everything about the gem, and plain `rake` at the root to run every gem's suite
+  or to validate this repo's own bundle.
+- **`CODE_OF_CONDUCT.md` no longer ships in the gem** (70 files, from 71). It is
+  a repository document and was packaged only because nothing rejected it. The
+  gem now carries **its own README** instead of the project's — which also fixes
+  a long-standing wart, since the project README opens with images under
+  `.github/` that the gemspec has never packaged, so the page on rubygems.org has
+  been rendering a broken hero.
+- `changelog_uri` points at `okf/CHANGELOG.md`, where this file now lives.
+
+### Fixed
+
+- **A directory really named `root` is nameable again.** `--dir` and `--area`
+  accept `root` as a spelling of the bundle root, which is worth a shell quote
+  right up until a bundle actually has a `root/` directory — and then the alias
+  made it unaddressable, answering for the bundle root instead: the wrong
+  concepts, exit 0, nothing said. The alias now yields to a real directory,
+  since a convenience is worth less than a directory being reachable at all;
+  where no such directory exists nothing changes, which is every bundle that
+  has ever relied on the spelling. `okf dirs` carried the same fold into its
+  `subtree` column, where it computed the `root` row's subtree against the
+  bundle root — so the number on the row disagreed with what `--dir` on that
+  row returns, the one thing it promises never to do.
+
+  "Does this bundle have a `root` directory?" is now asked of the bundle
+  (`Bundle#directories`, under Added above) rather than of whichever list a view
+  had to hand. The concept views were reading it off the *catalog*, which knows
+  only directories holding concepts, so a `root/` carrying nothing but an
+  `index.md` stayed folded in `catalog`/`files`/`tags`/`types`/`search` while
+  `dirs` and `index` named it correctly — two answers to one question about one
+  bundle. And a multi-bundle `okf search @a @b --dir root` resolved per bundle
+  inside the loop, so one flag meant the `root/` subtree in the bundle that has
+  one and the bundle root in the bundle that does not, merged into a single
+  ranking with nothing in the output saying so; the served set resolves it once.
+
+  `Bundle#directories` counts every file kind that makes a directory real —
+  concepts, an `index.md`, and now a scoped `log.md`, which the first cut left
+  out: a `root/` holding only its history was invisible to the set, so the
+  alias won again for exactly the shape the fix was named after, one file kind
+  over. The same seed feeds `directory_index`, so `dirs`, `index` and `stats`
+  count a log-only directory too, and every surface answers "does this bundle
+  have directory X?" from one list.
+- **`filter_entries` regained its 1.12.0 arity.** The dirs-source fix above
+  added a required third parameter to a helper on `CLI::Command` — the base
+  every verb inherits, plugin gems' verbs included — so an out-of-tree verb
+  calling the released two-argument shape raised `ArgumentError` at runtime.
+  The parameter defaults now, and the default is 1.12.0's resolution — the
+  helper is handed rows, not the folder, so it has nothing to resolve a real
+  `root/` against, and the `root` alias folds exactly as it did; the plugin
+  suite drives a 1.12.0-era verb through the two-argument shape to pin it.
+  Its sibling `filter_ids` makes the opposite choice on purpose: it *is*
+  handed the folder, and its two-argument shape resolves through `dir_scope`,
+  because the unconditional fold there was the bug this entry fixes, not a
+  contract — an old caller gets the corrected answer rather than the familiar
+  wrong one. In-tree callers pass
+  the set through `dir_scope`, which also derives it only when a `--dir` or
+  `--area` flag will actually consult it — a plain listing no longer pays a
+  per-path ancestor walk for a set nothing reads (and `Bundle#directories` is
+  memoized, so the verbs that ask twice pay once).
+- **Coverage stopped measuring the plugin's curation hook** for one commit, and
+  said so by going *up*: SimpleCov's root defaults to the working directory, so
+  moving the gem down a level dropped ~100 tested lines out of the report and
+  line coverage read 98.63% against 98.47%. Its root is the repository now, with
+  the report still written inside the gem.
+
+### Security
+
+- **A symlinked file in a bundle can no longer read past the bundle root.** The
+  traversal guard `Path.join_under!` was lexical — it expands the path string,
+  and `File.expand_path` does not resolve a symlink — so a link whose name sat
+  inside the root but whose target did not passed the check, and the read
+  followed it. Every read now realpath-resolves and re-checks against the real
+  root: `Path.under?` is the shared pure predicate, `Bundle::Reader` quarantines
+  an escaping file into the unparseable bucket (a planted symlink is one bad
+  file, not grounds to fail the whole bundle read, which would hand any writer of
+  a served directory a denial of service), and `Concept::File` guards its own
+  read. A symlink that stays inside the bundle still resolves as before. The gap
+  reached every reader; serving a bundle's contents to an agent — as `okf-mcp`
+  does — is what surfaced it.
+
 ## [1.12.0] - 2026-07-24
 
 ### Added
@@ -1223,6 +1516,9 @@ 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
 [1.10.0]: https://github.com/serradura/okf-gem/compare/v1.9.0...v1.10.0
 [1.9.0]: https://github.com/serradura/okf-gem/compare/v1.8.0...v1.9.0