okf 1.13.0 → 2.0.0

data/lib/okf/bundle/reader.rb

@@ -10,8 +10,8 @@ module OKF
     # index.md/log.md is kept as raw text (its structure is validated as text), and
     # a file the reader cannot use — frontmatter that does not parse, or a file it
     # cannot open at all — is retained as an unparseable entry (carrying the
-    # ParseError message or the errno, so §9.1 can report it) rather than dropped
-    # or raised. That tolerance is the whole §9 best-effort promise: one bad file
+    # ParseError message or the errno, so §11 condition 1 can report it) rather than dropped
+    # or raised. That tolerance is the whole §11 best-effort promise: one bad file
     # never breaks the rest, and this is the read every verb shares.
     #
     # Containment is enforced twice, because the two ways out of the root are
@@ -22,7 +22,7 @@ module OKF
     # location checked against the real root before a byte is read. An escaping
     # file joins the unparseable bucket rather than raising: a planted symlink is
     # one bad file, and letting it take down the whole bundle read would hand any
-    # writer of a served directory a denial of service. §9.1 then names it.
+    # writer of a served directory a denial of service. §11 condition 1 then names it.
     class Reader
       def self.read(dir)
         new(dir).read
@@ -72,7 +72,7 @@ module OKF
             # share — and in the worst way: a backtrace under an exit code that
             # claims non-conformance, or a served bundle taken down by one planted
             # symlink. So it joins the same bucket a bad frontmatter block does,
-            # and §9.1 reports it naming the file and the reason.
+            # and §11 condition 1 reports it naming the file and the reason.
             #
             # Its content is "" rather than nil: unknown, but every analyzer reads
             # it as text, and empty is the honest shape of a file we never read —
@@ -87,6 +87,12 @@ module OKF
 
       private
 
+      # Dir.glob's default (no FNM_DOTMATCH) excludes hidden files and every
+      # path under a hidden directory — kept deliberately, as the Unix
+      # convention it is: a bundle read from a project root must not pull in
+      # an installed skill under .claude/ or templates under .github/ as
+      # concepts. §3's taxonomy is read as covering the visible tree; the
+      # exclusion is documented in authoring.md and pinned by a reader test.
       def markdown_paths
         return [] unless Dir.exist?(@root)
 

data/lib/okf/bundle/references.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "set"
+
+module OKF
+  class Bundle
+    # The §6.3 inventory, pure: every file under `references/` — handed in by
+    # the shell as +files+, because the reader models concepts and this model
+    # performs no disk access — with which concepts cite each one through the
+    # §6.2 path-valued fields (resource, sources[].resource, computation,
+    # executor.resource, attester.resource), plus the pointers into
+    # `references/` that resolve to nothing.
+    #
+    # The bare-path trap is what the dangling list exists to surface: §6.2
+    # resolves a bare path relative to the concept, so `references/x` works
+    # from the bundle root and silently misses one directory down. When the
+    # missed spelling would have hit with a leading slash, the entry says so.
+    #
+    # Scope is the folder, by design. §6.3 is "a naming convention, not a
+    # requirement", and a computation stored beside its concept is legal —
+    # and deliberately not this inventory's to list.
+    class References
+      def self.build(bundle, files:)
+        new(bundle, files: files)
+      end
+
+      # Files under references/, sorted by path, each
+      # { path:, dir:, kind:, referenced_by: [ { id:, field: } ] } — kind is
+      # "concept" when the file is a parsed concept (§6.3 allows both), "file"
+      # otherwise. referenced_by is ordered by citing concept id.
+      attr_reader :entries
+
+      # Pointers into references/ that resolve to no file, ordered by concept
+      # id then field position, each { id:, field:, raw:, resolved:, hint: } —
+      # hint names the leading-slash fix when the bare spelling exists at the
+      # root, nil otherwise.
+      attr_reader :dangling
+
+      def initialize(bundle, files:)
+        @bundle = bundle
+        @files = files.sort
+        @existing = @files.to_set
+        build!
+      end
+
+      private
+
+      def build!
+        concept_paths = @bundle.concepts.to_set(&:path)
+        cited = {}
+        @dangling = []
+
+        @bundle.concepts.sort_by(&:id).each do |concept|
+          path_fields(concept).each do |field, raw|
+            target = Markdown::Links.resolve_path(raw, from: concept.path, bundle: @bundle.root)
+            next if target.nil? # external, empty, or a directory — not a file pointer
+
+            if @existing.include?(target)
+              (cited[target] ||= []) << { id: concept.id, field: field }
+            elsif under_references?(target) || bare_references?(raw)
+              @dangling << dangling_row(concept, field, raw, target)
+            end
+          end
+        end
+
+        @entries = @files.map do |path|
+          { path: path, dir: File.dirname(path),
+            kind: concept_paths.include?(path) ? "concept" : "file",
+            referenced_by: cited[path] || [] }
+        end
+      end
+
+      # Every §6.2 path-valued field this concept carries, as
+      # [ field-label, raw ] pairs. sources includes §13.1's lifted Citations —
+      # when the fallback is a concept's provenance, its pointers are too.
+      def path_fields(concept)
+        fields = [
+          [ "resource", concept.frontmatter["resource"] ],
+          [ "computation", concept.computation ],
+          [ "executor.resource", concept.executor && concept.executor["resource"] ],
+          [ "attester.resource", concept.attester && concept.attester["resource"] ]
+        ]
+        concept.sources.each_with_index do |source, index|
+          fields << [ "sources[#{index}].resource", source["resource"] ]
+        end
+        fields.reject { |_field, raw| OKF.blank?(raw) }
+      end
+
+      def under_references?(path)
+        path.to_s.start_with?("references/")
+      end
+
+      # The bare spelling of the trap: a raw that *names* references/ without
+      # the leading slash, which §6.2 resolves relative to the concept. From a
+      # subdirectory the resolved path leaves references/, so the target check
+      # above no longer sees it — the raw is what still does.
+      def bare_references?(raw)
+        raw.to_s.split("#", 2).first.to_s.start_with?("references/")
+      end
+
+      def dangling_row(concept, field, raw, target)
+        bare = raw.to_s.split("#", 2).first.to_s
+        hint = nil
+        if !bare.start_with?("/") && bare != target && @existing.include?(bare)
+          hint = "/#{bare} exists — missing leading slash?"
+        end
+        { id: concept.id, field: field, raw: raw.to_s, resolved: target, hint: hint }
+      end
+    end
+  end
+end

data/lib/okf/bundle/row_filter.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module OKF
+  class Bundle
+    # The one catalog-row predicate every narrowing surface shares — the CLI's
+    # filter flags, the MCP shell's catalog filters, and its search narrowing
+    # select rows by these rules and no other copy of them. The seam earned the
+    # module: the predicate was hand-spelled in three shells with only the leaf
+    # folds shared, and the copies diverged three recorded times (a raw status
+    # compare answering the opposite of `--status stable`, "" meaning no-filter
+    # on one tool and match-nothing on the next, the root's spellings).
+    #
+    # Callers hand it *normalized* wants — nil means "no filter", and `dir`
+    # arrives as a folded base path ("." for the bundle root) — because
+    # argument spelling is each shell's own: the CLI folds the `root` alias
+    # against the bundle's real directories, the MCP shell maps ""/"/" onto
+    # ".", and neither belongs here. Pure, like everything beside it.
+    module RowFilter
+      module_function
+
+      def matches?(row, type: nil, dir: nil, tag: nil, status: nil, trust: nil)
+        (type.nil? || fold(row[:type]) == fold(type)) &&
+          (dir.nil? || under_dir?(row[:dir], dir)) &&
+          (tag.nil? || Array(row[:tags]).any? { |value| fold(value) == fold(tag) }) &&
+          (status.nil? || Concept.effective_status(row[:status]) == Concept.fold_status(status)) &&
+          (trust.nil? || fold(row[:trust]) == Concept.fold_tier(trust))
+      end
+
+      # The one rule `--dir` is built on: a dir names itself and everything
+      # beneath it; "." is a prefix of nothing, so the root selects only what
+      # lives directly in it.
+      def under_dir?(entry_dir, base)
+        entry = fold(entry_dir)
+        path = fold(base)
+        entry == path || entry.start_with?("#{path}/")
+      end
+
+      def fold(value)
+        value.to_s.downcase
+      end
+
+      # The row-shaped spelling of Concept.shows_trust? — "is this row's tier one
+      # a surface should claim?". It lives beside #matches? because narrowing is
+      # one of its three consumers: the trust facet's gate, its counts and its
+      # narrowing all read this, so the facet describes exactly the rows wearing a
+      # tier. `generated` is the catalog's raw declared-key boolean, which is what
+      # tells a concept that opted into §5 from one that said nothing at all.
+      def shows_trust?(row)
+        Concept.shows_trust?(row[:trust], row[:generated])
+      end
+    end
+  end
+end

data/lib/okf/bundle/search.rb

@@ -99,14 +99,29 @@ module OKF
         "tags" => 3,
         "type" => 2,
         "description" => 2,
+        # A regression fix rather than a feature: in v0.1 a citation's text
+        # lived in the body and was searchable at weight 1. After a bundle
+        # migrates it lives in frontmatter, so without this a migrated bundle
+        # silently loses the hit entirely. What this restores is *recall* at
+        # the same weight — not an identical total. A v0.1 concept keeps
+        # matching `body` too, because the text really is body prose there, so
+        # it scores one higher than its migrated twin; that divergence is
+        # deliberate and pinned by cli_twins_test.rb ("migrating moves a
+        # source-only hit's snippet from body text to source text"). Suppressing
+        # it would mean lying about `--in body` on a bundle whose body does
+        # contain the words.
+        "sources" => 1,
         "body" => 1
       }.freeze
 
       FIELDS = WEIGHTS.keys.freeze
 
       # Fields whose match is only meaningful with surrounding context. The other
-      # fields already appear whole on the result row.
-      SNIPPET_FIELDS = %w[description body].freeze
+      # fields already appear whole on the result row. `sources` is here because
+      # indexed-but-un-snippeted would degrade a consumer's evidence line to a
+      # bare id list: after migration the snippet moves from body text to source
+      # text, it does not vanish.
+      SNIPPET_FIELDS = %w[description body sources].freeze
 
       # Characters of context kept on each side of the first matched term.
       SNIPPET_RADIUS = 44
@@ -195,6 +210,9 @@ module OKF
           "type" => concept.type.to_s,
           "description" => concept.description.to_s,
           "tags" => Array(concept.tags).join(" "),
+          # Titles and resources together: a source is findable by what it is
+          # called and by where it lives, which is how the body list read.
+          "sources" => concept.sources.flat_map { |source| [ source["title"], source["resource"] ] }.compact.join(" "),
           "body" => concept.body
         }
       end

data/lib/okf/bundle/validator/result.rb

@@ -3,7 +3,7 @@
 module OKF
   class Bundle
     class Validator
-      # The outcome of a §9 conformance check (see OKF::Bundle::Validator): hard `errors`,
+      # The outcome of a §11 conformance check (see OKF::Bundle::Validator): hard `errors`,
       # soft `warnings`, and file `counts`. Conformant iff there are no errors.
       class Result
         attr_reader :errors, :warnings, :counts
@@ -22,8 +22,11 @@ module OKF
           errors << { path: path, message: message }
         end
 
-        def add_warning(path, message)
-          warnings << { path: path, message: message }
+        # `check:` (a stable id) and `source:` (:spec | :convention) make a
+        # warning machine-readable; errors keep their exact two-key shape —
+        # consumers already read it, so new keys land on warnings only.
+        def add_warning(path, message, check: nil, source: nil)
+          warnings << { path: path, message: message, check: check, source: source }
         end
 
         def count(kind)

data/lib/okf/bundle/validator.rb

@@ -2,21 +2,36 @@
 
 module OKF
   class Bundle
-    # Checks an OKF::Bundle against the OKF v0.1 conformance rules (§9), which has
+    # Checks an OKF::Bundle against the OKF conformance rules (§11), which has
     # three conditions — all hard errors:
     #
-    #   §9.1  every non-reserved file has a parseable YAML frontmatter block;
-    #   §9.2  every such block has a non-empty `type`;
-    #   §9.3  every index.md/log.md present follows the §6/§7 structure — a nested
-    #         index.md has no frontmatter, a root index.md carries only okf_version,
-    #         and log.md date headings are ISO `YYYY-MM-DD`.
+    #   §11 c1  every non-reserved file has a parseable YAML frontmatter block;
+    #   §11 c2  every such block has a non-empty `type`;
+    #   §11 c3  every index.md/log.md present follows the §8/§9 structure — a nested
+    #          index.md has no frontmatter, a root index.md carries only okf_version,
+    #          and log.md date headings are ISO `YYYY-MM-DD`.
     #
     # Everything the spec marks as soft guidance is a warning and never makes a
     # bundle non-conformant: missing recommended fields, non-list tags, an
-    # unparseable timestamp, and broken cross-links (§5.3), which consumers MUST
-    # tolerate. Pure — it reads nothing from disk; it works entirely on the
-    # in-memory bundle.
+    # unparseable timestamp, broken cross-links (§6.1), and every v0.2 family
+    # shape (§5, §10). Pure — it reads nothing from disk; it works entirely on
+    # the in-memory bundle.
+    #
+    # Warnings are machine-readable: each carries a `check:` id and a `source:`
+    # naming who states the rule — `:spec` for the SPEC's own words,
+    # `:convention` for a shape this gem asks for beyond them. Errors keep their
+    # exact two-key shape; consumers already read it.
     class Validator
+      # The warnings that state a gem convention rather than a SPEC rule. §5.1
+      # gives `usage_count` no type and §10.2 marks only `runtime` REQUIRED;
+      # `verified[].by` is REQUIRED-within by analogy with `generated.by`, not
+      # by the SPEC's own words. A consumer that wants only the spec-normative
+      # warnings filters on `source:` instead of string-matching messages.
+      CONVENTION_CHECKS = %i[
+        verified_entry_by source_usage_count source_usage_window_shape
+        parameter_name executor_resource attester_resource
+      ].freeze
+
       def self.call(bundle)
         new(bundle).call
       end
@@ -36,20 +51,203 @@ module OKF
 
       private
 
-      # §9.2 (non-empty type) is the only hard error here; the missing recommended
-      # fields, non-list tags, and bad timestamp are soft warnings (never
-      # non-conformant). A parsed concept is valid UTF-8 by construction.
+      # Every warning goes through here so the check id and its source cannot
+      # drift apart: the id is the API, the source is derived from one constant.
+      #
+      # Not `warn`: that name shadows Kernel#warn for every method in the class,
+      # so a later `warn "…"` meant for stderr would raise ArgumentError at
+      # runtime — a collision neither RuboCop nor the call site can show you.
+      def record_warning(path, check, message)
+        @result.add_warning(path, message,
+          check: check,
+          source: CONVENTION_CHECKS.include?(check) ? :convention : :spec)
+      end
+
+      # §11.2 (non-empty type) is the only hard error here; the missing
+      # recommended fields, non-list tags, and bad timestamp are soft warnings
+      # (never non-conformant). A parsed concept is valid UTF-8 by construction.
       def validate_concept(concept)
         @result.count(:concepts)
         @result.add_error(concept.path, "frontmatter must include a non-empty type") if OKF.blank?(concept.type)
-        @result.add_warning(concept.path, "frontmatter should include title") if OKF.blank?(concept.title)
-        @result.add_warning(concept.path, "frontmatter should include description") if OKF.blank?(concept.description)
-        @result.add_warning(concept.path, "tags should be a list") if concept.frontmatter.key?("tags") && !concept.tags.is_a?(Array)
-        validate_timestamp(concept.path, concept.timestamp) if concept.frontmatter.key?("timestamp")
+        record_warning(concept.path, :recommended_title, "frontmatter should include title") if OKF.blank?(concept.title)
+        record_warning(concept.path, :recommended_description, "frontmatter should include description") if OKF.blank?(concept.description)
+        record_warning(concept.path, :tags_shape, "tags should be a list") if concept.frontmatter.key?("tags") && !concept.tags.is_a?(Array)
+        validate_iso8601(concept.path, :timestamp_format, "timestamp", concept.timestamp) if concept.frontmatter.key?("timestamp")
+        validate_families(concept)
         check_links(concept.path, concept.body)
       end
 
-      # §9.1: a concept-position file whose frontmatter did not parse. The message is
+      # ── the v0.2 families (§5, §10) ──────────────────────────────────────────
+      #
+      # Shape, and only shape: is it a mapping, does the date parse, is the enum
+      # value one the spec names. Whether a field is *missing*, *stale* or
+      # *unattributed* is curation, and the linter owns it — without that line the
+      # two would double-report every family.
+      #
+      # Every check reads the raw frontmatter key, never the fallback-carrying
+      # accessor — otherwise every v0.1 concept would warn about a mapping the
+      # §13.1 fallback synthesized, and "a pure v0.1 bundle validates silently"
+      # would stop being true. And every check is guarded by `frontmatter.key?`,
+      # so absence is never a fault: each family is optional (§5), and a v0.1
+      # concept that adopts none is a valid v0.2 concept. All warnings — §11's
+      # conformance conditions are only three.
+      def validate_families(concept)
+        validate_generated(concept)
+        validate_verified(concept)
+        validate_sources(concept)
+        validate_usage_window(concept)
+        validate_lifecycle(concept)
+        validate_computation(concept)
+      end
+
+      def validate_generated(concept)
+        return unless concept.frontmatter.key?("generated")
+
+        value = concept.frontmatter["generated"]
+        unless value.is_a?(Hash)
+          record_warning(concept.path, :generated_shape, "generated should be a mapping")
+          return
+        end
+
+        generated = Markdown::Frontmatter.stringify_keys(value)
+        record_warning(concept.path, :generated_by, "generated should include by") if OKF.blank?(generated["by"])
+        validate_iso8601(concept.path, :generated_at_format, "generated.at", generated["at"]) if generated.key?("at")
+      end
+
+      # §5.2 permits a list or a single bare mapping; anything else records no
+      # verification at all, which is what the warning is about.
+      def validate_verified(concept)
+        return unless concept.frontmatter.key?("verified")
+
+        value = concept.frontmatter["verified"]
+        return validate_verified_entries(concept, [ value ]) if value.is_a?(Hash)
+        return validate_verified_entries(concept, value) if value.is_a?(Array)
+
+        record_warning(concept.path, :verified_shape, "verified should be a mapping or a list of mappings")
+      end
+
+      def validate_verified_entries(concept, entries)
+        entries.each_with_index do |entry, index|
+          unless entry.is_a?(Hash)
+            record_warning(concept.path, :verified_entry_shape, "verified[#{index}] should be a mapping")
+            next
+          end
+
+          event = Markdown::Frontmatter.stringify_keys(entry)
+          record_warning(concept.path, :verified_entry_by, "verified[#{index}] should include by") if OKF.blank?(event["by"])
+          validate_iso8601(concept.path, :verified_entry_at_format, "verified[#{index}].at", event["at"]) if event.key?("at")
+        end
+      end
+
+      def validate_sources(concept)
+        return unless concept.frontmatter.key?("sources")
+
+        value = concept.frontmatter["sources"]
+        unless value.is_a?(Array)
+          record_warning(concept.path, :sources_shape, "sources should be a list")
+          return
+        end
+
+        value.each_with_index { |entry, index| validate_source(concept, entry, index) }
+      end
+
+      # `resource` is what makes a source addressable, so its absence is the one
+      # that matters most; `last_modified` and `usage_count` are the credibility
+      # signals with a shape to get wrong, and a per-entry `usage_window`
+      # override must be the same mapping the sibling is (§5.1).
+      def validate_source(concept, entry, index)
+        unless entry.is_a?(Hash)
+          record_warning(concept.path, :source_entry_shape, "sources[#{index}] should be a mapping")
+          return
+        end
+
+        source = Markdown::Frontmatter.stringify_keys(entry)
+        record_warning(concept.path, :source_resource, "sources[#{index}] should include resource") if OKF.blank?(source["resource"])
+        validate_date(concept.path, :source_last_modified, "sources[#{index}].last_modified", source["last_modified"]) if source.key?("last_modified")
+        if source.key?("usage_count") && !source["usage_count"].is_a?(Integer)
+          record_warning(concept.path, :source_usage_count, "sources[#{index}].usage_count should be an integer")
+        end
+        return unless source.key?("usage_window") && !source["usage_window"].is_a?(Hash)
+
+        record_warning(concept.path, :source_usage_window_shape, "sources[#{index}].usage_window should be a mapping")
+      end
+
+      def validate_usage_window(concept)
+        return unless concept.frontmatter.key?("usage_window")
+
+        value = concept.frontmatter["usage_window"]
+        unless value.is_a?(Hash)
+          record_warning(concept.path, :usage_window_shape, "usage_window should be a mapping")
+          return
+        end
+
+        window = Markdown::Frontmatter.stringify_keys(value)
+        %w[from to].each { |key| validate_date(concept.path, :usage_window_date, "usage_window.#{key}", window[key]) if window.key?(key) }
+      end
+
+      # §5.4 lets a producer use a status outside the three and requires consumers
+      # to tolerate it (§4.1), so this is a warning about a vocabulary a consumer
+      # keyed to the spec will not understand — never a rejection.
+      def validate_lifecycle(concept)
+        # fold_status, not effective_status: the §5.4 default belongs to a
+        # concept that never declared the key, and applying it here read a
+        # blank `status: ""` as `stable` — so the one value §5.4 names nowhere
+        # was the one value that never warned.
+        if concept.frontmatter.key?("status") && !Concept::STATUSES.include?(Concept.fold_status(concept.declared_status))
+          record_warning(concept.path, :status_vocabulary, "status should be one of #{Concept::STATUSES.join(", ")}")
+        end
+
+        validate_date(concept.path, :stale_after_format, "stale_after", concept.stale_after) if concept.frontmatter.key?("stale_after")
+      end
+
+      # §10.2 makes `runtime` REQUIRED for an Attested Computation — but §11's
+      # conformance conditions are only three, so its absence is a warning here
+      # and the linter owns the rest of the contract (one home per finding:
+      # shape and REQUIRED-within are the validator's side).
+      def validate_computation(concept)
+        if concept.attested_computation? && OKF.blank?(concept.frontmatter["runtime"])
+          record_warning(concept.path, :runtime_required, "runtime is required for an Attested Computation")
+        end
+
+        validate_parameters(concept)
+        validate_contract_mapping(concept, "executor", :executor_shape, :executor_resource)
+        validate_contract_mapping(concept, "attester", :attester_shape, :attester_resource)
+      end
+
+      def validate_parameters(concept)
+        return unless concept.frontmatter.key?("parameters")
+
+        value = concept.frontmatter["parameters"]
+        unless value.is_a?(Array)
+          record_warning(concept.path, :parameters_shape, "parameters should be a list")
+          return
+        end
+
+        value.each_with_index do |entry, index|
+          unless entry.is_a?(Hash)
+            record_warning(concept.path, :parameter_entry_shape, "parameters[#{index}] should be a mapping")
+            next
+          end
+
+          parameter = Markdown::Frontmatter.stringify_keys(entry)
+          record_warning(concept.path, :parameter_name, "parameters[#{index}] should include name") if OKF.blank?(parameter["name"])
+        end
+      end
+
+      def validate_contract_mapping(concept, key, shape_check, resource_check)
+        return unless concept.frontmatter.key?(key)
+
+        value = concept.frontmatter[key]
+        unless value.is_a?(Hash)
+          record_warning(concept.path, shape_check, "#{key} should be a mapping")
+          return
+        end
+
+        contract = Markdown::Frontmatter.stringify_keys(value)
+        record_warning(concept.path, resource_check, "#{key} should include resource") if OKF.blank?(contract["resource"])
+      end
+
+      # §11.1: a concept-position file whose frontmatter did not parse. The message is
       # the ParseError captured at read time.
       def validate_unparseable(entry)
         unless entry.content.valid_encoding?
@@ -85,46 +283,89 @@ module OKF
         frontmatter, = Markdown::Frontmatter.parse(content)
         extra_keys = frontmatter.keys - [ "okf_version" ]
         @result.add_error(path, "root index.md frontmatter may only include okf_version") if extra_keys.any?
+        validate_okf_version(path, frontmatter["okf_version"]) if frontmatter.key?("okf_version")
       rescue Markdown::Frontmatter::ParseError => e
         @result.add_error(path, e.message)
       end
 
+      # §12 asks a consumer to attempt best-effort consumption rather than
+      # refuse, so an unknown version is a warning and the bundle is read
+      # anyway; an absent one is the sanctioned MAY-not-declare case and never
+      # warns. Compared after `to_s.strip`: an unquoted `okf_version: 0.2` is a
+      # Psych Float, and warning on a correctly-declared bundle is the bug.
+      def validate_okf_version(path, declared)
+        return if OKF.blank?(declared) || Concept::KNOWN_SPEC_VERSIONS.include?(declared.to_s.strip)
+
+        record_warning(path, :okf_version_unknown,
+          "okf_version `#{declared}` is not a version this gem knows (read best-effort under §12)")
+      end
+
       def validate_log(path, content)
         content.each_line do |line|
           next unless line.start_with?("## ")
 
           heading = line.sub(/\A## /, "").strip
-          next if heading.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+          next if date_heading?(heading)
 
           @result.add_error(path, "log.md date headings must use YYYY-MM-DD")
         end
       end
 
-      # Broken bundle-internal links are warnings only (§5.3): the spec requires
+      # §9's MUST is ISO 8601, and 2026-02-30 is not a date — the digit shape
+      # alone accepted it, so a bundle could be conformant around a day that
+      # never existed. Same message either way: "must use YYYY-MM-DD" is as
+      # true of a February 30th as of a prose heading.
+      def date_heading?(heading)
+        return false unless heading.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+        Date.iso8601(heading)
+        true
+      rescue ArgumentError
+        false
+      end
+
+      # Broken bundle-internal links are warnings only (§6.1): the spec requires
       # consumers to tolerate them, so they never make a bundle non-conformant.
       def check_links(path, content)
         Markdown::Links.extract(content).each do |raw|
           resolved = Markdown::Links.resolve(raw, from: path, bundle: @bundle.root)
           next if resolved.nil? || @existing.include?(resolved)
 
-          @result.add_warning(path, "cross-link target not found: `#{raw}` (tolerated under §5.3)")
+          record_warning(path, :broken_link, "cross-link target not found: `#{raw}` (tolerated under §6.1)")
         end
       end
 
       # A YAML-parsed Date/Time is temporal by construction (YAML already validated
       # the shape); only a String needs checking, and it may be a full ISO 8601
       # datetime (2026-05-28T14:30:00Z) or a date-only value (2026-05-28).
-      def validate_timestamp(path, timestamp)
-        return if timestamp.is_a?(Date) || timestamp.is_a?(Time)
+      #
+      # `field` names what is being checked: one rule about what a moment looks
+      # like serves the legacy `timestamp`, `generated.at` and every
+      # `verified[].at`, reported against whichever field carried it.
+      def validate_iso8601(path, check, field, value)
+        return if value.is_a?(Date) || value.is_a?(Time)
 
-        value = timestamp.to_s
+        string = value.to_s
         begin
-          Time.iso8601(value)
+          Time.iso8601(string)
         rescue ArgumentError
-          Date.iso8601(value)
+          Date.iso8601(string)
         end
       rescue ArgumentError
-        @result.add_warning(path, "timestamp should be ISO 8601 parseable")
+        record_warning(path, check, "#{field} should be ISO 8601 parseable")
+      end
+
+      # §5.1/§5.5 want a calendar day, not a moment: `last_modified`,
+      # `usage_window.from`/`to` and `stale_after` are all YYYY-MM-DD. A YAML Date
+      # is one by construction; a Time is not — the extra precision means the
+      # producer wrote something else.
+      def validate_date(path, check, field, value)
+        return if value.is_a?(Date) && !value.is_a?(DateTime)
+
+        Date.iso8601(value.to_s)
+        record_warning(path, check, "#{field} should be a YYYY-MM-DD date") unless value.to_s.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+      rescue ArgumentError
+        record_warning(path, check, "#{field} should be a YYYY-MM-DD date")
       end
     end
   end

data/lib/okf/bundle/writer.rb

@@ -3,7 +3,7 @@
 module OKF
   class Bundle
     # Atomically writes a bundle to disk: renders concepts to a temp directory,
-    # validates it for §9 conformance (so a malformed bundle is never published),
+    # validates it for §11 conformance (so a malformed bundle is never published),
     # then promotes it into place under a lock. The disk-writing counterpart to
     # Reader.
     class Writer