okf 1.13.0 → 2.1.0

data/lib/okf/server/app.rb

@@ -18,16 +18,23 @@ module OKF
     #
     #   GET /               the interactive graph page (text/html)
     #   GET /node?id=…      the concept's raw markdown body (text/markdown)
-    #   GET /node/meta?id=… its description, as an escaped HTML fragment
+    #   GET /node/meta?id=… its description and null-stripped §5 trust fields —
+    #                       { description, trust: { tier, generated_by,
+    #                       generated_at, status, stale_after } } (JSON). The
+    #                       page composes the trust line client-side, once, for
+    #                       served and baked pages alike; expiry is the client's
+    #                       to compute, against the viewer's own today.
     #   GET /catalog        rich per-concept metadata for the catalog/files/stats
     #                       views: { concepts: [ {id, title, type, description,
-    #                       tags, timestamp, status, top_dir, dir, links_*} ] } (JSON)
+    #                       tags, generated_at, generated_by, generated, trust,
+    #                       status, stale_after, sources, top_dir, dir,
+    #                       links_*} ] } (JSON)
     #   GET /tags           the tag index  { tag  => [id, …] } (JSON)
     #   GET /types          the type index { type => [id, …] } (JSON)
-    #   GET /index          the §6 progressive-disclosure map for the Index panel:
+    #   GET /index          the §8 progressive-disclosure map for the Index panel:
     #                       { directories: [ …okf-index rows… ] } (JSON, from the
     #                       boot snapshot — authored maps are structure)
-    #   GET /log            the §7 history for the Log panel: { logs: [ {path,
+    #   GET /log            the §9 history for the Log panel: { logs: [ {path,
     #                       dir, content} ] } (JSON; content read live from disk,
     #                       like a body — the log is the file that changes most)
     #   GET /search?q=…     ranked concepts in this bundle, for the ⌘K palette:
@@ -143,14 +150,14 @@ module OKF
         { concepts: @folder.catalog }
       end
 
-      # The §6 map the Index panel renders — the same rows `okf index` prints,
+      # The §8 map the Index panel renders — the same rows `okf index` prints,
       # built by the pure OKF::Bundle#directory_index over the boot snapshot
       # (authored index bodies are structure, read at load like the graph).
       def directory_index
         { directories: @folder.directory_index }
       end
 
-      # The §7 history the Log panel renders: every log.md with its content, root
+      # The §9 history the Log panel renders: every log.md with its content, root
       # scope first, read live from disk. Built by OKF::Bundle::Folder#log_entries,
       # shared with `okf render`'s bake so the served and baked logs cannot drift.
       def logs
@@ -181,11 +188,19 @@ module OKF
         respond("text/markdown; charset=utf-8", concept.body)
       end
 
+      # JSON, not a fragment: a server-composed HTML line would be a second
+      # render path reaching innerHTML outside DOMPurify — the exact hole the
+      # self-contained-page rule names — and would need a byte-identical JS twin
+      # for the baked page anyway. The client owns the one composition, and
+      # every string here lands via textContent there.
       def node_meta(id)
         concept = concept_for(id)
         return not_found if concept.nil?
 
-        respond("text/html; charset=utf-8", description_fragment(concept))
+        payload = { "description" => concept.description.to_s }
+        trust = trust_fields(concept)
+        payload["trust"] = trust unless trust.empty?
+        respond_json(payload)
       end
 
       # Resolve an id to its concept, read live from disk. The id is only ever a key
@@ -200,11 +215,32 @@ module OKF
         nil
       end
 
-      def description_fragment(concept)
-        description = concept.description.to_s
-        return %(<span class="empty">no description</span>) if description.strip.empty?
+      # Null-stripped, and absent as a whole when a concept says nothing about
+      # its own provenance — a v0.1 concept that adopted no §5 family gets the
+      # panel it always had. The tier is skipped for unverified-and-undeclared
+      # through Concept#shows_trust?, the one predicate the card chip and the
+      # page's facets read too: an untouched v0.1 bundle must not read
+      # "unverified" on every panel. No expiry verdict is baked (the client
+      # compares dates with the viewer's today), and no actor is invented for a
+      # lifted timestamp.
+      def trust_fields(concept)
+        fields = {}
+        fields["tier"] = concept.trust if concept.shows_trust?
+        fields["generated_by"] = concept.generated_by
+        fields["generated_at"] = iso(concept.generated_at)
+        # The row's serialization, not the raw Psych value: `status: no` reads
+        # as false, blank?(false) is true, and stripping it here while the
+        # baked page reads the row's "false" split the served and baked
+        # inspectors over one concept.
+        fields["status"] = concept.declared_status&.to_s
+        fields["stale_after"] = iso(concept.stale_after)
+        fields.reject { |_, value| OKF.blank?(value) }
+      end
 
-        html_escape(description)
+      # The one temporal-serialization rule the catalog row keeps — shared, not
+      # mirrored, so /node/meta and the row cannot drift (see OKF.iso8601).
+      def iso(value)
+        OKF.iso8601(value)
       end
 
       def respond(content_type, body)
@@ -225,10 +261,6 @@ module OKF
       def not_found
         self.class.not_found
       end
-
-      def html_escape(str)
-        Rack::Utils.escape_html(str.to_s)
-      end
     end
   end
 end

data/lib/okf/server/hub.rb

@@ -599,7 +599,7 @@ module OKF
       end
 
       # ok / warn / error, with the word that carries the same message for a
-      # reader who cannot see the colour. validate and lint stay separate (§9):
+      # reader who cannot see the colour. validate and lint stay separate (§11):
       # a curation finding is a warning and never a conformance error, so a thin
       # bundle keeps its link and only a non-conformant one reads as broken.
       # Memoised like #counts — every stray 404 renders a bundle list too, and

data/lib/okf/skill/SKILL.md

@@ -35,13 +35,13 @@ Two ideas govern everything:
   declare a graph; it arises from how you link concepts. Good linking *is* good
   knowledge modelling.
 
-## The hard rules (§9 conformance)
+## The hard rules (§11 conformance)
 
 Three conditions, all hard — `validate` fails a bundle on any of them:
 
-1. **§9.1** every non-reserved `.md` file has a parseable YAML frontmatter block;
-2. **§9.2** every such block has a **non-empty `type`**;
-3. **§9.3** every reserved file present is well-formed — a nested `index.md` has
+1. **§11 cond. 1** every non-reserved `.md` file has a parseable YAML frontmatter block;
+2. **§11 cond. 2** every such block has a **non-empty `type`**;
+3. **§11 cond. 3** every reserved file present is well-formed — a nested `index.md` has
    no frontmatter, the bundle-root `index.md` carries *only* `okf_version`, and
    `log.md` date headings are ISO `YYYY-MM-DD`.
 
@@ -55,11 +55,11 @@ most common mistake:
 
 | Lens      | Question                          | Tool                    | Nature                    |
 |-----------|-----------------------------------|-------------------------|---------------------------|
-| **Legal** | Is it conformant OKF? (§9)        | `validate`              | Binary, tolerant          |
+| **Legal** | Is it conformant OKF? (§11)       | `validate`              | Binary, tolerant          |
 | **Good**  | Is it navigable, complete, fresh? | `lint`                  | Advisory, structural      |
 | **True**  | Is it consistent and *current*?   | *you*, over `lint --json` | Semantic — needs meaning |
 
-`validate` is *forbidden* by §9 from failing a bundle for broken links or missing
+`validate` is *forbidden* by §11 from failing a bundle for broken links or missing
 optional fields — that is `lint`'s job. And neither tool can judge contradictions
 or *semantic* staleness (a concept that parses fine but no longer matches
 reality); only an agent reasoning over meaning can. That last lens is where you
@@ -81,7 +81,7 @@ read and act on, never a missing toolchain to send to doctor.
 Don't memorize the surface — `okf --help` maps every verb, `okf <verb> --help` its
 flags. The division of labour is the whole game:
 
-- **Shell out — never eyeball —** anything a verb computes: conformance (§9), what
+- **Shell out — never eyeball —** anything a verb computes: conformance (§11), what
   exists, what links where, where a term lives, what's stale, the map. Every read
   verb takes `--json` and the list views filter by type/dir/tag, so ask the narrow
   question instead of paging the bundle.
@@ -92,21 +92,30 @@ flags. The division of labour is the whole game:
   (parses fine, no longer true), whether a loose file is terminal-by-design, whether
   a singleton tag is a deliberate marker. Tool output is evidence, never a verdict.
 
-The one trap worth carrying in your head: **freshness is off by default** — a plain
-`okf lint` never reports stale concepts; pass `--stale-after <90d|12w|ISO-date>`
-when the bundle carries timestamps. <!-- check:stale -->
-
-Read [cli.md](reference/cli.md) before *interpreting* a verb's output in depth:
-what `validate` may and may not reject, lint's categories and check ids, the JSON
-shapes, the tag-curation views, the server's trust boundary.
+The one trap worth carrying in your head: **the age cutoff is off by default** —
+a plain `okf lint` reports concepts past their own declared `stale_after` (the
+`expired` check reads the clock the CLI supplies), but never judges *age*; pass
+`--stale-after <90d|12w|ISO-date>` when you want anything not touched since then
+flagged too — the two mechanisms share a spelling and nothing else
+([cli/checks.md](reference/cli/checks.md), rule `okf-two-clocks`).
+<!-- check:stale -->
+
+Read [cli.md](reference/cli.md) before *interpreting* a verb's output in depth.
+It is the index and the shared contract — refs, exit codes, `--json`, the
+filters — and its table routes to the one file the verb lives in:
+[checks](reference/cli/checks.md) (what `validate` may and may not reject, lint's
+categories and check ids), [search](reference/cli/search.md),
+[map](reference/cli/map.md) (`index`/`dirs`), [views](reference/cli/views.md)
+(the tag-curation views), [serve](reference/cli/serve.md) (the trust boundary),
+[registry](reference/cli/registry.md), [graph](reference/cli/graph.md).
 
 ## Orient before you touch anything
 
 Picking up a bundle you don't already know — to consume or maintain — start with
 `okf dirs <dir|@slug>`: one row per *directory*, so it stays small on a bundle of
 any size and it names the branches every other view narrows to. Then open the one
-you want with `okf index <dir|@slug> --dir <branch>` (the §6 map: that directory's
-index body, rollups, and listing), and read `log.md` (the §7 baseline of what
+you want with `okf index <dir|@slug> --dir <branch>` (the §8 map: that directory's
+index body, rollups, and listing), and read `log.md` (the §9 baseline of what
 changed last) — all of it **before** greping or opening leaves. Reach for `index`
 rather than grep for the one reason that outranks convenience: **grep cannot find
 an index entry that is missing**, so enumeration drift is invisible to it — you
@@ -121,8 +130,9 @@ playbooks (the Commands table below; no `okf` installed? read the root
 `consume` (use it as context) carry the judgment the executable can't — this is
 where the skill earns its keep. Each has a playbook (the Commands table below);
 read the modelling craft in [authoring.md](reference/authoring.md) before
-producing or maintaining, and the verbatim spec [SPEC.md](reference/SPEC.md)
-when you need chapter and verse.
+producing or maintaining. When you need chapter and verse, go through
+[spec-map.md](reference/spec-map.md) — which § settles which question — into the
+verbatim [SPEC.md](reference/SPEC.md).
 
 **No subcommand?** Infer intent: "document this / capture X" → `produce`;
 "convert / migrate / OKFy these existing docs into a bundle" → `migrate`; "the

data/lib/okf/skill/playbooks/curate.md

@@ -20,11 +20,16 @@ mis-homed hubs, an uncurated tag layer — that is [refine](refine.md).
    `okf loose <root> --json`.
 3. Interpret through the three lenses the okf skill teaches, and keep them
    separate:
-   - conformance errors (§9) are the only hard failures; fix them first,
+   - conformance errors (§11) are the only hard failures; fix them first,
      always;
    - lint findings are curation debt across reachability, backlog,
-     completeness, freshness, provenance, and hygiene. They are advisory;
-     rank them by how much each hurts a reader navigating the graph;
+     completeness, freshness, provenance, attestation, migration, and hygiene.
+     They are advisory; rank them by how much each hurts a reader navigating
+     the graph. Read the stats' `trust` and `status` distributions for the
+     bundle's posture (how much is unverified, what is draft or deprecated),
+     and treat the Migration findings as an offer, not debt — §13 keeps a v0.1
+     bundle consumable forever, and the [migrate playbook](migrate.md) carries
+     the rewrite when the user wants it;
    - loose files can be legitimate terminal leaves, so judge each one before
      linking it anywhere.
 4. Propose, then apply: list the fixes worth making (must-fix errors first,

data/lib/okf/skill/playbooks/doctor.md

@@ -39,7 +39,9 @@ Verify with `okf --version` before moving on.
    directory, or a root `index.md` whose frontmatter carries `okf_version`.
 2. Found one? Run `okf validate <root>` and `okf lint <root>`, then summarize
    in a few lines: conformant or not (and the errors if not), the warning
-   count, and the top curation findings by category.
+   count, the top curation findings by category, the trust/status posture the
+   lint stats report, and — when the Migration category fires — that the bundle
+   still writes v0.1 spellings and the skill's migrate playbook can move them.
 3. No bundle? Offer to bootstrap one. The okf skill knows how (its "produce"
    workflow); do not scaffold anything without the user's yes.
 

data/lib/okf/skill/playbooks/maintain.md

@@ -6,8 +6,8 @@ up. Restructuring the bundle itself — moving concepts, adding areas — is
 lives in [authoring.md](../reference/authoring.md).
 
 1. **Orient before hunting.** Run `okf dirs <dir>` (the shape), then `okf index
-   <dir> --dir <branch>` on the branch the change touches (the §6 map: its index
-   body, rollups and listing), read `log.md` (the §7 baseline: what changed
+   <dir> --dir <branch>` on the branch the change touches (the §8 map: its index
+   body, rollups and listing), read `log.md` (the §9 baseline: what changed
    last), and `okf stats <dir>` (size and shape) *before* you grep. It is the
    cheapest context and it primes the hunt — and it is the only reliable way to
    catch enumeration drift, because **grep cannot find an index entry that is
@@ -19,18 +19,21 @@ lives in [authoring.md](../reference/authoring.md).
    cannot express — and `okf graph <dir> --json --minimal` to pull the edges (the
    concepts that link *to* the ones you're touching) without paying for every body.
    Let search and the graph find them so nothing drifts silently.
-3. Update bodies and `timestamp`; fix or add cross-links; create new concepts for
+3. Update bodies and `generated.at` (and `generated.by` — who is making this
+   change, in §7's spelling); fix or add cross-links; create new concepts for
    new assets; mark retired assets with a `**Deprecation**` note rather than
    silently deleting the context that explains them.
 4. **Update every enumeration that names what you changed — including `index.md`
    bodies**, not just the concept files: a new, renamed, or removed concept changes
-   its directory's index listing too. Append a dated `log.md` entry. Step 1's map
+   its directory's index listing too. Append a dated `log.md` entry — what changed and why it
+   matters, never the rounds it took (rule `okf-log-durable-only` in
+   [authoring.md](../reference/authoring.md)). Step 1's map
    is how you verify this — re-run `okf index` and confirm each listing matches
    reality.
 5. Run `validate`, then `lint` to catch the curation drift the change introduced —
-   new orphans, broken citations, dangling index entries. Add `--stale-after`
-   (e.g. `90d`) if concepts carry timestamps: freshness is off by default, so a
-   plain `lint` will not tell you what the change left stale.
+   new orphans, broken sources, dangling index entries, footnotes that lost
+   their source. `expired` reports out of the box; add `--stale-after`
+   (e.g. `90d`) when you also want an age cutoff, which stays off by default.
 6. **Review loose files** <!-- check:unlinked --> — run `okf loose <dir>` (the
    folder-grouped view of `lint`'s `unlinked` check): the concepts with **no
    cross-links in or out**, which

data/lib/okf/skill/playbooks/menu.md

@@ -21,7 +21,7 @@ is the lede.
    text views, which are lighter than `--json` when you are reading a report
    rather than extracting structure from it. Then recommend by what they
    report, most-blocking first:
-   - **`validate` has errors** → lead with **`curate`**: §9 conformance errors are
+   - **`validate` has errors** → lead with **`curate`**: §11 conformance errors are
      the only hard failures, and curate fixes them before anything else.
    - **clean `validate`, but `lint`/`loose` findings** → lead with **`curate`** to
      settle the curation debt (reachability, backlog, completeness, hygiene),
@@ -39,9 +39,10 @@ is the lede.
      with almost no internal traffic in `okf graph --traffic` → offer
      **`refine`** (evidence-driven restructuring; it proposes before it
      touches anything).
-4. **Freshness is off by default.** If the bundle carries timestamps, note that a
-   plain `lint` said nothing about staleness and `okf lint <root> --stale-after
-   90d` is the check that would.
+4. **The age cutoff is off by default.** A plain `lint` already reports concepts
+   past their own declared `stale_after` (`expired`), but says nothing about
+   *age*; when the bundle records change times, note that `okf lint <root>
+   --stale-after 90d` is the check that would.
 
 Keep it to two or three pointed picks, each with the exact `/okf:gem <verb>` to
 run and a one-line reason from the signals. Never auto-run a workflow from here.

data/lib/okf/skill/playbooks/migrate.md

@@ -20,23 +20,46 @@ non-trivial migration; its type and tag rules apply here unchanged.
    block of [templates/concept.md](../templates/concept.md): a small `type`
    vocabulary derived from what the documents *are* (reuse before minting —
    check `okf types <dir>` as you go), `title`/`description` from each
-   document's own heading and purpose line, `timestamp` from the document's own
-   date when it carries one, `tags` only where connective.
+   document's own heading and purpose line, `generated: { by: <actor>, at: … }`
+   from the document's own history when it carries one (the actor in §7's
+   spelling — never invented), `tags` only where connective.
 3. **Keep the directory topology** — it is already domain knowledge. Default
    one file = one concept. When a file shows split signals (two `type`s
    fighting for the frontmatter, two audiences), flag it for a later `curate`
    pass; never split, rename, or restructure during migration.
 4. **Reserved files.** A bundle-root `index.md` from
    [templates/root-index.md](../templates/root-index.md) (frontmatter is
-   `okf_version: "0.1"` and nothing else), a nested `index.md` per directory
+   `okf_version: "0.2"` and nothing else), a nested `index.md` per directory
    from [templates/index.md](../templates/index.md), and `log.md` with a dated
    **Creation** entry naming where the documents came from.
 5. **Links.** The documents' existing relative links become the graph's edges —
    verify they resolve inside the bundle and repoint only what a move broke.
-   Links pointing outside the bundle are tolerated (§5.3); leave them.
+   Links pointing outside the bundle are tolerated (§6.1); leave them.
 6. **Close out** — walk the
    [Closeout gate](../reference/authoring.md#closeout--the-finishing-gate):
-   `validate` zero errors, `lint` (pass `--stale-after` when you stamped
-   timestamps), `loose`, tag review, index eyeball. Then prove the promise:
-   each concept with its frontmatter block stripped is byte-identical to the
-   source document.
+   `validate` zero errors, `lint`, `loose`, tag review, index eyeball. Then
+   prove the promise: each concept with its frontmatter block stripped is
+   byte-identical to the source document.
+
+## The other migration: v0.1 spelling → v0.2
+
+A bundle already in OKF but written in v0.1's spelling reads correctly forever
+(§13.1), so this pass is convenience — run it when you want the bundle to *write*
+what v0.2 readers expect. Exactly two spellings move, and `lint`'s Migration
+findings name every file carrying either:
+
+1. Run `okf lint <dir>` and read the two Migration findings — `legacy_timestamp`
+   and `legacy_citations` list the affected files in their metric.
+2. **`timestamp` → `generated`.** Move the value under
+   `generated: { by: <actor>, at: <the timestamp> }`. The actor is the one thing
+   no tool can derive: ask, or write `human:<maintainer>` when the history is
+   human — and never let a tool sign a person's name (see
+   [produce](produce.md)).
+3. **`# Citations` → `sources`.** Lift each item into a `sources:` entry —
+   a labelled link's text becomes `title`, its URL `resource`; a bare-URL or
+   autolink item has no title, so keep `resource` alone or author one. Where
+   the body cites a source, add an `id:` to the entry and a `[^id]` footnote at
+   the claim. Then delete the section.
+4. Re-run `okf lint` until the Migration category is clean. The mechanical
+   done-check, exit 1 until it is:
+   `okf lint <dir> --only legacy_timestamp,legacy_citations --fail-on info`.

data/lib/okf/skill/playbooks/produce.md

@@ -1,24 +1,33 @@
 # Playbook: produce — create or extend a bundle
 
 The craft that makes these steps land well — granularity, choosing `type`, tag
-vocabulary, topology, links, citations — lives in
+vocabulary, topology, links, sources — lives in
 [authoring.md](../reference/authoring.md). Read it before a non-trivial produce.
 
-1. Read [SPEC.md](../reference/SPEC.md) if you are unsure of any rule.
+1. Unsure of a rule? [spec-map.md](../reference/spec-map.md) names the § that
+   settles it; read that section of [SPEC.md](../reference/SPEC.md).
 2. Pick the source(s): **code** (derive concepts from source, READMEs, docstrings,
-   config), **docs/wiki** (distill pages into concepts; cite the originals under
-   `# Citations`), **manual** (decisions, playbooks, metrics that live only in
-   people's heads). If the source documents should survive as the concepts
-   themselves — verbatim — that is [migrate.md](migrate.md), not produce.
+   config), **docs/wiki** (distill pages into concepts; record the originals in
+   `sources:` and key claims with `[^id]` footnotes), **manual** (decisions,
+   playbooks, metrics that live only in people's heads). If the source documents
+   should survive as the concepts themselves — verbatim — that is
+   [migrate.md](migrate.md), not produce.
 3. Choose a domain-based directory layout. One concept per file.
-4. Write each concept from [templates/concept.md](../templates/concept.md): a
-   descriptive `type` from the bundle's vocabulary, recommended fields filled,
-   cross-links to related concepts written into prose.
+4. Write each concept from [templates/concept.md](../templates/concept.md) — or
+   [templates/attested-computation.md](../templates/attested-computation.md)
+   when the concept *is* a sanctioned computation (§10): a descriptive `type`
+   from the bundle's vocabulary, recommended fields filled, cross-links to
+   related concepts written into prose. `generated.by` says who produced the
+   content, in §7's spelling — and when a tool writes a concept unattended, the
+   tool writes **its own** identity, `<producer>/<version>`: `human:<maintainer>`
+   from a generator would be a fabricated human attestation, the exact false
+   provenance §5 exists to prevent.
 5. Add or refresh `index.md` per directory from
    [templates/index.md](../templates/index.md); for the bundle root use
    [templates/root-index.md](../templates/root-index.md) so it carries
-   `okf_version: "0.1"`. Append a dated entry to `log.md`.
+   `okf_version: "0.2"`. Append a dated entry to `log.md`.
 6. **Close out** — walk the
    [Closeout gate](../reference/authoring.md#closeout--the-finishing-gate)
-   (`validate` + `lint` are part of it, see [cli.md](../reference/cli.md))
+   (`validate` + `lint` are part of it, see
+   [cli/checks.md](../reference/cli/checks.md))
    before finishing.

data/lib/okf/skill/playbooks/search.md

@@ -3,7 +3,7 @@
 Reached by `search <query…>` — the query is everything after the verb; given no
 query, ask what to find. Retrieval matters as much as curation: a bundle nobody
 can query cheaply is dead weight. The discipline is progressive disclosure
-(spec §6): every step pays a few hundred bytes to decide what the next step
+(spec §8): every step pays a few hundred bytes to decide what the next step
 reads, and full bodies are read last, and only the winners.
 
 1. **Just run it — no presence probe.** Point the finder at a path or an `@slug`
@@ -58,7 +58,7 @@ reads, and full bodies are read last, and only the winners.
    @slugs (`okf search @handbook @notes <terms>`) or `@all` for every registered
    one — and read the per-row bundle slug before following an id home.
 4. **Read only the winners.** A match row's `id` is its file: `<dir>/<id>.md`.
-   Read that file — not its folder, never the whole tree. Follow its links (§5)
+   Read that file — not its folder, never the whole tree. Follow its links (§6)
    one hop at a time; check `log.md` when freshness matters.
 5. **Answer, then write back.** Cite the concept ids you used. If the answer
    was missing, stale, or needlessly hard to find — a gap, a broken link, an