okf 1.13.0 → 2.0.0

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,7 +19,8 @@ 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`
@@ -28,9 +29,9 @@ lives in [authoring.md](../reference/authoring.md).
    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,23 +1,30 @@
 # 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.
 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))

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