/okf-pro

name: okf-pro
description: Operating rules for the .okf/ knowledge bundle — filing new concepts, the board, the journal, the daily snapshot, closing work, source attribution, and the generated/verified attestation policy. Use before reading from or writing anything into .okf/.

Operating the bundle

Everything here is relative to `.okf/`, the bundle root — `reference/` below is `.okf/reference/` on disk, and a link written `/reference/thing.md` inside a concept resolves there.

What to load

This file is the whole of the three rules and the routing question, and it is the part every session needs. Two things come before opening any guide: the CLI already answers most questions about state, and the line shapes are below.

Ask the CLI before you read a file

State is computed, not read. Every row below is one call answering what several `cat`s answer, and the first row costs nothing at all — it is already in front of you.

| to answer | run | not | |---|---|---| | what is on the board / what is in flight | *(already in the session banner)* | `cat board.md` | | the board after you changed it | `okf pro state` | re-reading the file | | one row per board line, with dates and links | `okf pro board` | counting headings by eye | | what awaits the owner's read | `okf pro unverified` | grepping frontmatter | | the day's snapshot line | `okf pro snapshot` | computing it by hand | | every invariant at once | `okf pro audit` | — |

And five writes have exactly one correct form, so they are verbs rather than shapes to reconstruct. Each is additive and targeted: it appends a line or edits the line you named, refuses if the change it computed is not the change it declared, and never rewrites a file.

| to do | run | |---|---| | capture something into the Inbox | `okf pro capture "the words you heard"` | | move a line to In flight (refuses over the cap) | `okf pro promote <selector>` | | move one back to Backlog | `okf pro demote <selector>` | | open today's journal day and index it | `okf pro journal open` | | the three mechanical closing moves | `okf pro close <project>` |

A `<selector>` is a `/projects/<slug>` link, a bare slug, or a substring only one line carries — never a position. Two lines matching is a refusal, not a coin toss.

Add `--json` to `state`, `board`, `snapshot`, `unverified` or `friction` when you want to compute on the answer rather than read it; `okf pro state --full` adds the corpus-derived parts behind one parse. `audit` and `records` answer with their exit code and take no flags.

**The line shapes, so you do not have to open a guide for them.** A board line starts `- ` at column zero — a `*` bullet or an indented dash is invisible to every counter, including the cap. Inbox and Deadlines lines lead with the date: `- YYYY-MM-DD — <the words>`. A Waiting line carries `chase YYYY-MM-DD`, literally. A conflict line is an Inbox line reading `- YYYY-MM-DD — Resolve: [/a.md] says X, [/b.md] says Y — noticed while <doing what>`. The closure marker is the word then the date with only spaces, a colon, a dash, asterisks or an opening parenthesis between: `# Title — closed 2026-08-12`. That is a deliberate partial duplication of the guides, and the guides remain the full reference — this is here so the commonest question does not cost a file read.

The guides

Each *act* has its detail one file away. Load the one the task calls for, not all five.

• [guides/frontmatter.md](guides/frontmatter.md) — the *trust* family

this profile adds on top of the format: `generated:`, `verified:` and the tiers they produce, `status:`, and the `stale_after:` windows. **Before writing any concept, and whenever provenance is the question.**

• [guides/board.md](guides/board.md) — the six sections, the date

grammar the counters actually read, and what makes a line invisible to them. **Before editing `board.md`.**

• [guides/attribution.md](guides/attribution.md) — `sources:`, and the

keyed footnotes that tie one claim to one source. **Before filing anything into `reference/`.**

• [guides/closing.md](guides/closing.md) — the four moves that close a

piece of work, and the exact spellings of the closure marker. **Before marking a project closed.**

• [guides/okf-rules.md](guides/okf-rules.md) — the *format's* floor,

which holds for any OKF bundle and not just this profile: the three required frontmatter keys, directory indexes, link form, the log entry. **When `okf validate` or `okf lint` disagrees with you.**

Read this list permissively. A guide that is missing does not suspend the rule it explains — the three rules below are operative on their own, and the gates enforce them whether the file explaining them was read or not. A file in `guides/` that this list does not mention still counts: the index is a map, not a permission list, and adding your own guide beside these is expected. Anything here you do not recognise — an extra heading, a `<!-- rule: … -->` marker, a file kind you have not seen — is left alone rather than treated as an error.

The three zones

| Zone | Directory | What lives there | |------|-----------|------------------| | **KNOW** | `reference/` | What other people produced — summarised, cited, attributed. | | | `learnings/` | What I concluded, true beyond the work that produced it. | | | `glossary/` | What a word means here, when it means three things elsewhere. | | **ACT** | `projects/` | Work with a definition of done. Closes. | | | `areas/` | A standard held indefinitely. Never closes. | | **TIME** | `board.md` | The single page of forward state — the whole commitment surface. | | | `journal/` | The backward record, one entry per day, append-only. | | | `roadmap.md` | The quarterly wavelength. Sparse, links out. |

Where a new concept goes

One question routes almost everything: **does it outlive the piece of work that produced it?**

• **No — it is work-scoped** → `projects/<slug-or-key>/`. Meeting notes,

the decision that only makes