okf-pro 1.0.0

data/.okf/design/a-rule-you-can-walk-past.md

@@ -0,0 +1,68 @@
+---
+type: Learning
+title: A rule you can walk past is a preference
+description: Why the gates block rather than warn, why three doors are not redundant, and why the day's ritual must stay silent on a day nobody worked.
+---
+
+# The claim
+
+Every knowledge system that has ever failed its owner failed the same way: the
+discipline was real for three weeks, then it was optional, then it was gone. A
+warning you can dismiss is a preference with better typography, and the dismissal
+becomes reflex faster than the habit does.
+
+So the checks refuse. The edit does not land.
+
+# What a refusal owes the person it stops
+
+Three properties, and a message missing any of them trains people to route
+around the gate rather than to comply with it:
+
+* **It names the rule that fired.** Not "invalid" — the rule, by number and in
+  words, so the refusal teaches the system it is enforcing.
+* **It names the escape.** The cap is the adopter's own; going to six is
+  allowed. What is forbidden is going to six *silently*. A rule with no
+  legitimate exit gets disabled the first time it is genuinely wrong, and takes
+  the rest of the gates with it.
+* **It forces the comparison being avoided.** To promote a sixth thing you have
+  to look at five commitments and say which is worth less. That comparison is
+  the actual work of prioritisation, and without a ceiling nobody ever performs
+  it — they only add.
+* **The escape it names has to work.** The stop gate refuses a Snapshot line
+  that disagrees with the board and prints the recomputed line, because the fix
+  is a paste. A capture dated in the future gives a *negative* age; `render`
+  wrote `oldest -365d` while the parse pattern demanded a digit straight after
+  `oldest `, so the gate disagreed with the line it had itself just generated —
+  and refused the paste it had just recommended. One mistyped year, and the only
+  way out was to find a typo no gate was pointing at. A rule with no legitimate
+  exit gets disabled the first time it is genuinely wrong; a rule whose *stated*
+  exit does not work is that same failure with a false floor under it, because
+  the reader spends their patience before they start looking.
+
+  The repair is not to make the counter agree by making it lie. Clamping the age
+  at zero would have made the gate self-consistent and `oldest 0d` unexplainable,
+  which is the quiet-wrong-number failure derivation exists to refuse. A negative
+  age is the honest reading of a future-dated capture, so both halves read it:
+  render writes it and parse accepts it.
+
+# Why three doors are not two too many
+
+Each door sees edits the others structurally cannot. The agent hooks fire at the
+tool boundary, so an edit made in an editor never reaches them — which is why
+the commit door asks git directly. A clone that never ran `core.hooksPath` has
+no commit door at all — which is why CI asks a third time. None of the three is
+a belt-and-braces copy of another; each is the only witness to a class of edit.
+
+# The counterweight: never bill a ritual for opening a file
+
+A gate that fires on the calendar rather than on the work teaches people to
+ignore it, and it is the same wolf-crying failure that
+[Law 2](/design/three-laws.md)'s limit names. So the stop gate asks whether any
+markdown in the bundle is actually dirty before it asks for anything: a session
+that read the bundle and changed nothing closes in silence.
+
+The confessed cost of that choice: a counter drifted by an editor edit stays
+invisible until the next session stops, because `audit` checks that the day's
+snapshot is present and not that its numbers are current. Preferring a
+late-and-trusted gate to a punctual one nobody reads is the trade, made
+deliberately.

data/.okf/design/derivation-that-writes.md

@@ -0,0 +1,161 @@
+---
+type: Decision
+title: Derivation may write, under a conservation guard
+description: Failure mode 07 forbids an LLM regenerating a view; it does not forbid a Ruby function performing a declared, line-conserving edit — and the status quo it was written against was the failure mode itself.
+---
+
+# The verdict, read precisely
+
+Failure mode 07 — **Agent Drift** — is stated in the lineage's design record as:
+
+> An LLM regenerating a view drops a task, silently — no error, no diff anyone
+> reads, one commitment gone. Closed by: the split. Derivation exists as a
+> checker and never as a generator: a thing that computes and refuses has no
+> way to drop anything in silence.
+
+[snapshot](/design/three-laws.md) is built on that, and it stands: `okf pro
+snapshot` computes the day's line and prints it, and the stop gate verifies the
+line a person appended. Nothing writes it.
+
+But the verdict names two things — **derivation** (recomputing a whole view and
+writing it back) and **an LLM** (the actor). Neither is what a mechanical writer
+does, and reading the rule as "no verb may ever write" left the status quo in
+place: the agent rewrote `board.md` with a shell heredoc. That is the
+silent-drop hazard exactly, performed by exactly the actor the record names. The
+prohibition was protecting the failure mode rather than the bundle.
+
+# What the write verbs may do, and what makes it enforceable
+
+> **Additive and targeted, never regenerative.** A write verb may append a line
+> or edit the line it was given. No verb rewrites a file it did not fully derive
+> from that file's own prior contents. A writer never satisfies its own gate.
+
+That sentence is a promise, and a promise is what mode 07 already broke once.
+`Conserve` is what converts it into a property: every write verb computes its
+new text purely, **declares the delta it intends** — added, removed, moved —
+and hands before, after and claim to a guard that compares line multisets. If
+the actual delta is not the declared one, the verb exits 2 and the file is
+untouched.
+
+The asymmetry matters in both directions. A line added that nobody claimed is a
+finding; so is a claimed addition that never happened, because an edit that did
+less than it said is how a promotion silently no-ops and reports success.
+
+A Ruby function that provably cannot drop a line is the remedy for a heredoc
+that can, and the difference between them is that this one is checked.
+
+# What the guard cannot supply, and what it cannot see
+
+**A satisfied checker is not a correct edit.** `close` marks a project index by
+appending the closure marker to its first line, and guarded that by asking
+whether the result satisfied `Pairing::MARKER`. It did — for a file whose first
+line is `---`. `Pairing.marker?("--- — closed 2026-08-17")` is true, because
+the regex needs only the word and a date. So an index carrying YAML frontmatter
+had its fence destroyed, the concept silently lost its `type`, `title` and
+`description`, and `okf validate` still exited 0. `Conserve` could not see it
+either: the mangling *was* the declared edit.
+
+The fix is to check the SHAPE of the line being edited, not only the shape of
+the result: the first line must be a markdown heading, because that is where
+the skill teaches the marker and the only place `closed?` looks. The general
+form of the lesson is that a conservation guard proves a line was not dropped
+and proves nothing about whether the right line was chosen — the choice needs
+its own precondition.
+
+**Decide about every file before writing any of them.** `close` touches three,
+and `write_atomically` makes each write atomic and the set not. Checking as it
+went produced a real half-closed bundle: a board that had lost its budget
+header refused at step two with the index already marked, so the project read
+as closed while its board line survived and no log entry existed — and the
+refusal message said nothing had happened. Every check now runs and every new
+text is computed before anything lands, so a *refusal* writes nothing at all,
+which is what the message claims. The residue of a crash mid-sequence is still
+real, and still visible to `okf pro audit`; the residue of a refusal is now
+none.
+
+**A verb that turns a name into a path owes a containment decision — twice.**
+`File.join` resolves `..` without comment, so `okf pro close ../../somewhere`
+would put a closure marker on a stranger's index. A project is one directory
+segment by the structure's own rule, so anything else is refused rather than
+normalised — quietly rewriting a path the caller gave is how a traversal
+becomes an edit nobody sees.
+
+A validated name is not a contained path, though, and the second half was
+missing: `projects/<slug>` can be a **symlink** out of the bundle, and `close`
+read and rewrote it with the uncontained pair while `Pairing.closed?` refused to
+read the very same file and answered *open*. The write landed outside the bundle
+and the checker then denied it had happened.
+[containment-directions](/contract/containment-directions.md) carries the rule
+that came out of it: the read door and the write door are two decisions about
+one path, and they must agree.
+
+**The guard's refusal is only as good as the line it names.** `set_declared`
+found the budget header per line and spliced it back per substring, so a prose
+line quoting the header was rewritten instead. `Conserve` saw the delta was not
+the declared one and wrote nothing, exactly as designed — and then named the
+prose line, leaving the board unpromotable until somebody edited text that was
+never at fault. A guard that refuses correctly and points somewhere useless is
+still a verb the user cannot get past.
+
+**A selector has to name a thing.** They are keyed and never positional, and
+they refuse on ambiguity — but `select` only refuses on more than one match, so
+a selector that matched *everything* still went through wherever exactly one
+line was in range. `/` and `/projects` chomp to a prefix that is a proper
+ancestor of every linked line, and `start_with?` turns the name into a wildcard;
+the empty-selector guard had the argument written down and covered one spelling
+of it. A directory every project sits under names none of them.
+
+**And a writer's first positional is content, which makes a flag data.** The
+write verbs take no flags, so `okf pro capture --help` appended
+`- <date> — --help` to the Inbox and exited 0. A verb whose failure mode is
+committing a garbage board line has to refuse a leading dash rather than
+swallow it; `--` is the escape for the rare content that really does begin with
+one.
+
+# What still may not be written
+
+* **A view regenerated from anything but its own prior contents.** The rule is
+  the file's text in, the file's text out, plus a named delta.
+* **`snapshot --write`.** A writer and a checker sharing a code path agree
+  trivially and prove nothing; the stop gate keeps its independent read.
+* **A concept body.** Prose is judgment, and judgment is the skill's. `close`
+  performs its three mechanical moves and reports the durable extraction to
+  `learnings/` as owed.
+* **`verified:`.** The owner's approval is the attestation
+  ([trust/read-owed-rule](/trust/read-owed-rule.md)); a verb that wrote it would
+  be manufacturing the one thing the whole trust surface measures.
+* **A seeded file that is missing.** `capture` will not create `board.md` — a
+  board written by a verb is a board nobody decided the shape of — and the same
+  answer holds for `journal/index.md`, which `journal open` appends a line to.
+  Rebuilding it from the one line the verb knows how to write returns a file
+  holding only that line: the `# Journal` heading and the seeded prose gone,
+  under a message reporting success. That is regeneration wearing an append's
+  clothes, and the giveaway is that the output does not depend on the input.
+  The sibling policy is the rule: a write verb refuses a missing file and names
+  the audit that reports it.
+
+# The safety property the guards cannot supply
+
+A verb invoked through Bash is seen by neither `guard-verified` (Edit and Write
+only) nor `shell-guard` (there is no mutator pattern in `okf pro capture`). So
+the write verbs are safe **by construction** rather than by being watched:
+agent-supplied text reaches a board line body or a journal entry body and
+nowhere else, and text spanning lines is refused rather than escaped — a
+one-line write is a write that cannot carry a `---`.
+
+The third piece is the one that only exists because a verb now takes a *name*
+from the caller and turns it into a *path*. `okf pro close <slug>` marks a
+file's first line, and `File.join` resolves `..` without comment — so a slug
+that can leave `projects/` puts a closure marker on a stranger's index. A
+project is one directory segment by the structure's own rule, so anything else
+is **refused rather than normalised**. Quietly rewriting a path the caller gave
+is how a traversal becomes an edit nobody sees, and it is the same instinct
+[containment-directions](/contract/containment-directions.md) records for reads:
+one decision per call site, made out loud.
+
+The selectors carry the other half. They are keyed — a `/projects/<slug>` link,
+or a substring only one line holds — and they **refuse on ambiguity** instead of
+picking. A positional index is what
+[structure-laws](/design/structure-laws.md)'s keyed-identity rule forbids, for
+the reason this whole file is about: agents rewrite, and "the third line under
+Backlog" names a different commitment after any edit anyone makes.

data/.okf/design/failure-modes.md

@@ -0,0 +1,43 @@
+---
+type: Finding
+title: The eight failure modes
+description: The named ways a personal knowledge system dies — three by lying and five by telling the truth badly — and the mechanism that answers each.
+---
+
+# The catalogue
+
+Every rule in this design exists because one of these demanded it. None is
+hypothetical.
+
+| # | Failure | Closed by |
+|---|---------|-----------|
+| 1 | **The Flood** — weeks without triage, and the tidy view cannot signal its own incompleteness | the snapshot delta: inbox count and oldest age, read against yesterday's line |
+| 2 | **Contradiction Cascade** — Monday's doc says X, Wednesday's thread Y, Friday's ticket Z, all fresh, all verified | triage as a read before a write; capture the decision's timestamp, not the artifact's |
+| 3 | **Cross-Cutting Meeting** — a meeting kills a project offscreen and the absence of a link is invisible | triage asking *what does this make untrue?*, not only *where does this belong?* |
+| 4 | **Ghost Project** — a deprioritised project never closes and crowds the view | dormancy, derived from journal links: still in flight, or backlog pretending? |
+| 5 | **The Liar** — a misheard number, captured and verified: maximum trust, false claim | not closable — [the residue](/design/the-residue.md). Mitigated by the source pointer |
+| 6 | **Amnesia Week** — journal completeness inversely correlates with workload | declared reconstruction: rebuild from `log.md` and git history, and say in the entry that you did |
+| 7 | **Agent Drift** — an LLM regenerating a view drops a task silently | the checker/generator split, plus the conservation guard where a verb does write — [derivation-that-writes](/design/derivation-that-writes.md) |
+| 8 | **Priority Inflation** — everything becomes priority one and priority stops carrying information | the cap: promotion requires demotion, and position replaces priority syntax |
+
+# The split that matters
+
+Three of these are the system **lying** — 2, 3 and 5. Provenance and
+reconciliation close them.
+
+The other five are the system **telling the truth badly**: incomplete, noisy,
+inflated, thin. Not one false statement between them, and the terminal state is
+identical — you stop reading it. That is the finding the design is built on:
+**attention, not truth, is the scarce resource**, and no frontmatter field ever
+fixed an attention leak. It is why the laws are behavioural.
+
+# The same standard, applied to the gates themselves
+
+The enforcement layer is held to this from the other side, and its own bug
+history says why: every defect it has produced failed open *while looking like
+it had run* — a missing parser, a misspelled variable, a rescued error, a wrong
+event shape, a stray binary on PATH. Silent incompleteness is failure mode 1
+wearing the checker's uniform, which is why the gates refuse on their own
+absence ([contract/the-contract](/contract/the-contract.md)) and why the suite
+is weighted toward the degraded paths
+([testing/drills-over-units](/testing/drills-over-units.md)).

data/.okf/design/index.md

@@ -0,0 +1,18 @@
+# Design
+
+Why the rules exist, and what each one was paid for.
+
+The other areas document the machinery — the contract it keeps, the seam it
+enters through, what it writes, how it is tested. This one documents the
+argument that machinery serves: which named failure each rule closes, which
+limit it admits, and which parts are borrowed rather than invented.
+
+* [three-pillars](three-pillars.md) - Know, Work, State — and why the third is the one neither source had.
+* [three-laws](three-laws.md) - The behaviour the gates enforce, each with the limit it admits.
+* [the-residue](the-residue.md) - Trust measures process, never truth. The one failure no law closes.
+* [failure-modes](failure-modes.md) - The eight ways a system like this dies, and the mechanism that answers each.
+* [structure-laws](structure-laws.md) - A directory is a retrieval question, not a subject.
+* [a-rule-you-can-walk-past](a-rule-you-can-walk-past.md) - Why a refusal blocks instead of warning, and why it stays silent on days nobody worked.
+* [a-comment-is-not-an-implementation](a-comment-is-not-an-implementation.md) - A regex that claimed to anchor `>` never did, and the guard fired on reads for its whole life.
+* [derivation-that-writes](derivation-that-writes.md) - Failure mode 07 forbids an LLM regenerating a view, not a declared, line-conserving edit.
+* [lineage](lineage.md) - What CODE, PARA and GTD supplied, what was deliberately left, and where this design breaks with them.

data/.okf/design/lineage.md

@@ -0,0 +1,95 @@
+---
+type: Overview
+title: Lineage
+description: What CODE and PARA supplied, what GTD supplied, what was deliberately left behind, and the three points where this design breaks with both its sources.
+sources:
+  - id: basb
+    resource: https://www.buildingasecondbrain.com/
+    title: Building a Second Brain
+    author: Tiago Forte
+  - id: gtd
+    resource: https://gettingthingsdone.com/
+    title: Getting Things Done
+    author: David Allen
+---
+
+# Nothing here is invented from nothing
+
+Two established systems supply most of the machinery. A third pillar was added
+because both share the same blind spot. Stating the debts precisely is not
+courtesy: a borrowed rule carries the reasoning that justified it, and a rule
+whose provenance is lost gets re-argued from scratch every time someone
+questions it.
+
+# Building a Second Brain — the Know and Work pillars
+
+CODE (Capture, Organize, Distill, Express) treats knowledge as something that
+moves, and its load-bearing insight is that **distillation is a separate act
+from capture**.[^basb] Systems that collapse the two become archives nobody
+rereads. PARA files by actionability rather than by topic — not *where does this
+belong subject-wise*, a question with no stable answer, but *what is my
+relationship to this right now*.[^basb]
+
+**Taken:** capture as a distinct, near-frictionless step; distillation as its own
+act, which is why `learnings/` exists at all; actionability as the filing axis;
+and projects-drive-to-done against areas-maintain-a-standard — a distinction
+[Law 3](/design/three-laws.md) later needed, because legitimate stillness in an
+area is what keeps the dormancy alarm from crying wolf.
+
+**Left:** Resources as one room, split three ways because it was three retrieval
+questions. Archives as a *place* — it became a status, since moving files breaks
+citations. And tool-agnostic vagueness: this design commits to plain files in a
+validating format.
+
+# Getting Things Done — the Work and State pillars
+
+GTD's durable insight is psychological before it is organisational: an open loop
+held in the head consumes attention whether or not you act on it, and the cure
+is externalising into a system you actually trust.[^gtd] Trust is the operative
+word — a system you half-believe is worse than none, because you keep a shadow
+copy in your head anyway.
+
+**Taken:** ubiquitous capture, and the claim that trust is the whole product;
+next action, singular and physical, which is why the board holds one line per
+demand and the full list stays in the project; waiting-for as its own class with
+a chase date, because it is the category that rots silently; and a recurring
+ritual as the thing that keeps state true, which here became the end-of-day
+sitting.
+
+**Left:** contexts (`@phone`, `@computer`), an artifact of a pre-mobile world.
+The unbounded next-actions list — a list with no ceiling is precisely how
+priority inflation sets in. Someday/maybe as a dumping ground, replaced by a
+Backlog that is visible and counted. And the habit heuristics, which are
+behaviour rather than structure.
+
+# The Board — what neither source had
+
+Both are blind to time. PARA says where a thing lives, CODE says how knowledge
+matures, and neither says what today looks like or leaves a record of what
+happened. GTD has lists but no memory: it faces relentlessly forward, and a done
+item evaporates. Ask any of them what you worked on in March and what changed,
+and there is no answer.
+
+What the third pillar makes computable is set out in
+[three-pillars](/design/three-pillars.md); the short version is that dormancy,
+invisible labour, and Law 2's deltas all require a system that remembers its own
+previous state.
+
+# Where this design breaks with its sources
+
+* **Both assume a human author.** Accountability could stay implicit when
+  everything in the system was typed by the person who trusted it. Once an agent
+  writes a hundred concepts an hour that guarantee is gone, and provenance has to
+  become explicit — `generated:`, `verified:`, and the rule that an agent may
+  summarise but may never conclude that what it summarised needs nothing.
+* **Both treat structure as personal.** This design treats it as enforceable: a
+  validating format, hooks that refuse, a pre-commit that audits, CI that blocks.
+  Not rigour for its own sake — a system co-written with agents needs rules that
+  are executable rather than remembered.
+* **Neither confesses.** PARA never says *this folder may be incomplete*; a GTD
+  list never says *I have not been reviewed in three weeks*. Law 2 is the
+  genuinely new demand, and it is the one that most changes daily experience.
+
+Law 1 is the other new requirement, and it belongs to the era rather than to the
+sources: when writing is cheap and plentiful, the scarce discipline is
+confronting what is already there.

data/.okf/design/structure-laws.md

@@ -0,0 +1,46 @@
+---
+type: Decision
+title: Structure laws
+description: The seven rules that decide whether a room, a field or a file may exist — a directory is a retrieval question, and state lives in exactly one place.
+---
+
+# The rules
+
+* **A directory is a retrieval question; a type is ontology.** A room pays rent
+  by answering a question no other room answers. This is why `reference/`,
+  `learnings/` and `glossary/` are three rooms and not one: *what others
+  produced*, *what I concluded* and *what a word means here* are three different
+  questions asked at three different moments.
+* **State lives in exactly one place.** Listings enumerate, never aggregate. The
+  second copy agrees; the third one rots, and nobody can tell which is current.
+* **Location is filing; lifecycle is metadata.** Nothing moves on a status
+  change. Closure, deprecation and staleness are fields and markers, because a
+  move breaks every citation pointing into the thing that moved, to buy a
+  tidiness nobody asked for.
+* **Capture is a line, not a file.** A staging folder is a blind spot by
+  construction — things enter it and are never enumerated again. The attention
+  claim and the artifact are separate objects, and only the first one is urgent.
+* **A maintained view survives by being bounded.** Next-action-only is what
+  makes hand maintenance honest: if it is bounded enough to maintain, it is
+  bounded enough to read at a glance. A board carrying every step is a project
+  plan wearing a board's clothes.
+* **No new room until an incident forces it.** Rooms are cheap to add and
+  expensive to retire, and an empty room still costs a decision every time
+  something is filed.
+* **Instructions are not knowledge.** A file is in the bundle because it answers
+  a retrieval question. Rules, documentation and code live outside it, without
+  frontmatter. This one was paid for: `README.md` and `CLAUDE.md` once carried
+  `type:` for no reason but their address.
+
+# Why they are stated as laws rather than preferences
+
+Each one is a veto that can be applied to a proposal in the moment it is made,
+by someone who was not there when the design was argued. "Where would this go?"
+is a question with no stable answer; "what question does this room answer that
+no other room does?" has exactly one, and it is usually *none*.
+
+The rules also compose with the three behavioural laws
+([three-laws](/design/three-laws.md)) rather than sitting beside them. Bounded
+views are Law 3 applied to a page. One-place state is what lets Law 2's
+confession be recomputed and checked. Capture-as-a-line is what keeps the
+five-second cost that makes Law 1's ingestion checkpoint reachable at all.

data/.okf/design/the-residue.md

@@ -0,0 +1,44 @@
+---
+type: Learning
+title: The residue
+description: Trust measures process, never truth — a misheard number, sourced and verified, reaches maximum trust while being false, and no law closes it.
+---
+
+# The limit
+
+`generated:` and `verified:` say how a claim arrived, who looked at it, and when
+it expires. They never say that it is true. Mishear a number, capture it,
+source it perfectly, read it yourself and attest to it, and the concept reaches
+the top trust tier carrying a false claim — faithfully, exactly as designed.
+
+This is not a gap to be closed in a later version. It is the ceiling on what any
+provenance system can promise, and it is stated on every tier of the design
+rather than buried, because a design that implies otherwise is more dangerous
+than one that says so plainly. A reader who believes the tiers measure truth
+will stop checking; a reader who knows they measure process keeps checking, which
+is the behaviour the whole apparatus is trying to preserve.
+
+A passport proves who issued it, when, and that the process was followed. It
+cannot prove the bearer is a good person. Nothing in this design is a lie
+detector.
+
+# What the mitigation actually buys
+
+The source pointer. Not truth — **falsifiability**. A claim that names where it
+came from can be checked later by someone who doubts it, and everything derived
+from it can be found and re-examined when it turns out to be wrong. A claim with
+no pointer cannot be reconciled at all, which is why the pointer is also
+[Law 1](/design/three-laws.md)'s precondition and not merely good manners.
+
+So the honest promise is: a well-sourced mistake stays catchable. That is the
+best a knowledge system can offer, and anything promising more is selling
+something.
+
+# Why the trust tiers are read off the actor, not off truthiness
+
+The vocabulary that carries this is v0.2's — a `verified` entry by a `human:`
+actor makes a concept human-reviewed, anything else machine-confirmed, no entry
+at all unverified ([trust/read-owed-rule](/trust/read-owed-rule.md)). The tiers
+describe *who performed which process*, which is exactly the claim the design
+can support. A tier that meant "checked and correct" would be the residue
+denied.

data/.okf/design/three-laws.md

@@ -0,0 +1,71 @@
+---
+type: Decision
+title: Three laws
+description: Nothing is written without confronting what is already there; every view confesses its blind spots; attention is a budget, renegotiable but never silently exceeded.
+---
+
+# The laws
+
+> **Law 1 — Writing is reconciliation.** Nothing enters the corpus without
+> confronting what is already there.
+>
+> **Law 2 — Every view confesses its blind spots.** A view states what it
+> cannot see with the same prominence as what it can.
+>
+> **Law 3 — Attention is budgeted, not requested.** Anything claiming attention
+> draws from a finite, visible budget.
+
+Every failure in [failure-modes](/design/failure-modes.md) traces to one of the
+three, plus one thing no law closes ([the residue](/design/the-residue.md)).
+They are behavioural rather than schema because the deaths they prevent are
+attention leaks, and no frontmatter field has ever fixed one.
+
+# Each law's admitted limit
+
+The limit is the load-bearing half. A law stated without one invites the
+confidence that makes it dangerous.
+
+**Law 1 catches contradictions as well as your recall does, and no better.**
+Vocabulary drift defeats it silently: two concepts that disagree in words you
+did not think to search for never meet. So the law is a ratchet with two
+checkpoints rather than a guarantee — search at ingestion, collision at read
+time — and the consequence is that `index.md` (findability) and `glossary/`
+(vocabulary) are this law's load-bearing organs, not hygiene.
+
+**Law 2's confession must be a delta, not a status.** A permanent "47
+untriaged" banner becomes wallpaper: a confession that is always present carries
+zero information, and a check that always cries trains its reader to skip it —
+at which point Law 2 has started violating Law 3. `inbox 14` says nothing;
+`+8 inbox, oldest now 6d` says what the week did to you.
+
+**Law 3's cap is renegotiable, never silently exceeded.** Eight critical things
+against a cap of five is not a bug in the cap — it is overload made undeniable
+on the day it happens, forced into a conversation instead of accumulating
+privately. Raising the cap is the system working; a visible renegotiation is
+journal-worthy. What is forbidden is pretending the table seats six.
+
+# Where each law lives
+
+* **Law 1** — `reconcile-search` fires on every new concept and returns the
+  colliding vocabulary while the write is still hot. What cannot be settled on
+  the spot becomes a dated conflict line on the board, where it competes under
+  the cap: an unresolved contradiction is work.
+* **Law 2** — the end-of-day snapshot line in `log.md`, read against yesterday's.
+  The confession structurally cannot lie: the stop gate recomputes every counter
+  and refuses a line that disagrees with the board it summarises, carrying the
+  recomputed line in the refusal. A checker, never a generator — see Agent Drift
+  in [failure-modes](/design/failure-modes.md).
+* **Law 3** — the `In flight: k/CAP` header. Promotion requires demotion.
+  Dormancy asks after `Budget::DORMANCY_DAYS` working days, quiet while the
+  journal is younger than its own window, because a bundle in its first week is
+  new rather than dormant. `roadmap.md` is the same budget at quarterly
+  wavelength.
+
+# Every number here is a guess until use tunes it
+
+The cap of five, the five-working-day dormancy window, the seven-day deadline
+lookahead, the staleness table: none is derived from anything. They are
+visible-and-wrong by design — a number in a header that someone argues with is
+worth more than a number nobody can see. When one proves wrong in use, the
+change is a decision in the adopter's own `areas/corpus.md` first, then the
+rule, then a log line.

data/.okf/design/three-pillars.md

@@ -0,0 +1,48 @@
+---
+type: Overview
+title: Three pillars
+description: Know, Work and State — three questions no one of them can answer alone, and why the zones of the bundle are the pillars themselves.
+---
+
+# The three questions
+
+* **Know** — *what do I know?* `reference/` (what other people produced),
+  `learnings/` (what I concluded), `glossary/` (what a word means here).
+* **Work** — *what am I responsible for?* `projects/` drives to done, `areas/`
+  maintains a standard indefinitely.
+* **State** — *what am I doing, and what did I do?* `board.md` is the forward
+  lens, `journal/` the backward one, and `log.md` remembers yesterday's numbers.
+
+The zones are not a filing convenience laid over the pillars; they **are** the
+pillars, which is why the tree has no room that answers to none of the three.
+Everything around `.okf/` — instructions, hooks, workflows, this gem — is
+enforcement or code, and none of it is knowledge.
+
+# Why State is a pillar and not a view
+
+Know and Work are borrowed and unoriginal, and deliberately so
+([lineage](/design/lineage.md)). State is the addition, and it earns pillar
+status rather than sitting as a rendering of the other two because three
+capabilities exist only once a system remembers its own previous state:
+
+* **dormancy** — an in-flight demand no journal entry has linked in five
+  working days must re-justify its slot. The signal is derived from the
+  temporal record; a pure filing system cannot compute it.
+* **invisible labour becomes evidence** — a hallway decision produces no
+  artifact, so the journal is its only proof at review time.
+* **deltas** — the whole refinement of
+  [Law 2](/design/three-laws.md) needs yesterday's numbers to compare against.
+
+Ask a filing system what happened in March and it has nothing to say. That
+silence is what the third pillar answers.
+
+# Where two pillars touch
+
+A capture is one dated line on the board — the claim on attention lands in
+State while the artifact, if there ever is one, files into Know. The inbox line
+is that seam, and it costs five seconds on purpose: capture that costs more
+stops happening on exactly the days it matters most, which are the busy ones.
+
+Splitting the two is also what keeps a staging folder out of the design. An
+`inbox/` directory would be a blind spot by construction — see
+[structure-laws](/design/structure-laws.md).

data/.okf/index.md

@@ -0,0 +1,31 @@
+---
+okf_version: "0.2"
+---
+
+# okf-pro knowledge bundle
+
+The non-obvious knowledge behind **okf-pro** — the gem that turns an
+[okf](@okf) bundle into a working memory an agent is held to. The `README`
+documents the verbs and the scaffold, and `AGENTS.md` carries the contracts a
+change has to keep; this bundle deliberately restates neither.
+
+It captures two things. The first is the argument the gem serves — three laws,
+the failures each one closes, and the limit each one admits — because the rules
+are borrowed and reasoned rather than obvious, and a rule whose reasoning is
+lost gets re-argued from scratch every time someone questions it.
+
+The second is the thing this gem is unusual for: **every defect here fails
+in the direction of silence.** A gate that cannot run, a check that was skipped,
+a shim on PATH, a status code the protocol reads as "proceed" — each of them
+produces an unchecked bundle that is indistinguishable, from the outside, from a
+clean one. So the knowledge worth recording is not what the checks assert; it is
+where the machinery around them can stop asserting anything without saying so.
+
+# Areas
+
+* [Design](design/) - Why the rules exist: three pillars, three laws, the eight failures they close, and what was borrowed.
+* [Contract](contract/) - Fail closed, fail loud, never fail silent — and the exit codes that make it true.
+* [Seam](seam/) - The plugin entry point, the three ways it fails open, and the wrapper that closes them.
+* [Scaffold](scaffold/) - What `setup` writes, who owns each file afterwards, and why no date ships.
+* [Trust](trust/) - The v0.2 read-owed rule, and the four call sites that must agree about it.
+* [Testing](testing/) - Drills over unit tests, and the fixture that is a client of the code it tests.