okf-pro 1.0.0

data/lib/okf/pro/state.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # What is on the board, in one call.
+    #
+    # THE MEASUREMENT THIS EXISTS FOR. A session adding one task to a seeded
+    # bundle spent 40.9% of its tool output rediscovering state — the board, the
+    # log, the project and journal indexes, read raw, one `cat` per question —
+    # and called no `okf pro` verb at all. Nine calls answered what the gates
+    # already compute on every Stop. So there is no new logic here: every
+    # aggregation below already existed and was consumed only by a refusal.
+    #
+    # CHEAP BY DEFAULT, and that is a contract rather than an optimisation. The
+    # default payload reads `board.md`, `log.md` and two directory globs, and
+    # parses no concept — the same sources the session banner uses, so a reader
+    # can trust the two to agree. `--full` is where `Bundle::Reader.read` lives:
+    # the attestation report, the pairing invariants, and the live unverified
+    # count, behind ONE parse shared by all three.
+    #
+    # A contract that names its sources is a contract to check before adding
+    # one. The friction log was added here and did not belong: it is telemetry
+    # about the tooling rather than state of the bundle, it is append-only with
+    # nothing pruning it, and `render` never printed the field — so the cheap
+    # default paid for an unbounded read only `--json` could see.
+    # `okf pro friction` is the verb that answers it.
+    #
+    # Shell, not core: it reads the disk. The arithmetic it reports is Board's,
+    # Log's, Snapshot's and Pairing's, all of it pure and all of it already
+    # tested against text rather than against a fixture.
+    module State
+      module_function
+
+      def call(root, today: Date.today, full: false)
+        board = Pro.read_text(File.join(root, "board.md"))
+        log_path = File.join(root, "log.md")
+        log = File.exist?(log_path) ? Pro.read_text(log_path) : ""
+        vis = Board.visible(board)
+
+        payload = {
+          "root" => root,
+          "as of" => today.to_s,
+          "board" => board_state(vis, today),
+          "deadlines at risk" => Snapshot.looming_deadlines(vis, today).map(&:strip),
+          "log" => log_state(root, log, today),
+          "projects" => { "open" => Pairing.open_projects(root).sort },
+          "last snapshot" => last_snapshot(log)
+        }
+        payload["full"] = full_state(root, board) if full
+        payload
+      end
+
+      def board_state(vis, today)
+        budget = Board.budget(vis)
+        inbox = Board.visible_section_lines(vis, "Inbox")
+        waiting = Board.visible_section_lines(vis, "Waiting")
+        ages = inbox.map { |l| Board.line_date(l) }.compact.map { |d| (today - d).to_i }
+        {
+          "in flight" => Board.visible_section_lines(vis, "In flight").size,
+          "cap" => budget&.cap,
+          "declared" => budget&.declared,
+          "backlog" => Board.visible_section_lines(vis, "Backlog").size,
+          "waiting" => waiting.size,
+          "past chase" => waiting.map { |l| Board.chase_date(l) }.compact.count { |d| d < today },
+          "inbox" => inbox.size,
+          "oldest" => ages.max || 0,
+          "to read" => Board.visible_section_lines(vis, "To read").size,
+          "deadlines" => Board.visible_section_lines(vis, "Deadlines").size,
+          "conflicts open" => Snapshot.conflicts(vis)
+        }
+      end
+
+      def log_state(root, log, today)
+        {
+          "newest day" => Log.newest_day(log),
+          "journal today" => File.file?(File.join(root, "journal", "#{today}.md"))
+        }
+      end
+
+      # Labelled by the day it was logged under, never as live. The counters
+      # here are free — the banner already prints the line, and parsing it costs
+      # a regex — but two of them (`unverified briefings`, `projects with 0
+      # concepts`) can only be recomputed by parsing the bundle, so a reader
+      # who is told them without the date would read a stale number as current.
+      def last_snapshot(log)
+        day, line = Log.latest_snapshot_entry(log)
+        return nil if line.nil?
+
+        { "day" => day, "line" => line.strip, "counters" => Snapshot.parse(line) }
+      end
+
+      # The one parse, shared by all three. Ordered so the reader meets the
+      # invariants before the listing: a pairing failure is a thing to fix, and
+      # an unverified concept is the truth about what is owed.
+      def full_state(root, board)
+        concepts = ::OKF::Bundle::Reader.read(root).concepts
+        {
+          "pairing" => Pairing.failures(root, board: board, concepts: concepts).map { |m| m.sub(/\A— /, "") },
+          "unverified" => Attestation.report(root, concepts: concepts).map(&:strip),
+          "unverified briefings" => Pairing.unverified_ids(concepts).size
+        }
+      end
+
+      # ── human rendering ──────────────────────────────────────────────────
+      #
+      # The default, because the consumer is also a person doing QA — and
+      # because a human line an agent reads costs the same tokens as JSON it
+      # has to re-serialise into prose anyway.
+      # The board's counters as one line, and the ONE place they are formatted.
+      # `okf pro state` and the session banner both print it, and the banner's
+      # whole promise is that it says what the verb would say — two renderings
+      # of the same eleven numbers would drift into a reader having to check
+      # which one they were looking at.
+      def board_line(board, label)
+        "#{label} in flight #{board["in flight"]}/#{board["cap"] || "?"} · backlog #{board["backlog"]} · " \
+          "waiting #{board["waiting"]} (#{board["past chase"]} past chase) · inbox #{board["inbox"]} " \
+          "(oldest #{board["oldest"]}d) · to read #{board["to read"]} · deadlines #{board["deadlines"]} · " \
+          "conflicts open #{board["conflicts open"]}"
+      end
+
+      def render(payload)
+        b = payload["board"]
+        lines = [ board_line(b, "Board —") ]
+        if b["declared"] && b["declared"] != b["in flight"]
+          lines << "  header declares #{b["declared"]} in flight and the section holds " \
+                   "#{b["in flight"]} — fix the header."
+        end
+
+        risk = payload["deadlines at risk"]
+        unless risk.empty?
+          lines << "Deadlines within 7d with nothing in flight against them:"
+          risk.each { |line| lines << "  #{line}" }
+        end
+
+        log = payload["log"]
+        lines << "Log — newest day #{log["newest day"] || "none yet"} · journal for " \
+                 "#{payload["as of"]} #{log["journal today"] ? "open" : "not opened"}"
+
+        open_projects = payload["projects"]["open"]
+        lines << "Open projects (#{open_projects.size})#{": #{open_projects.join(", ")}" unless open_projects.empty?}"
+
+        lines.concat(render_snapshot(payload["last snapshot"]))
+        lines.concat(render_full(payload["full"])) if payload["full"]
+        lines
+      end
+
+      def render_snapshot(snap)
+        return [ "Last snapshot: none yet" ] if snap.nil?
+
+        counters = snap["counters"]
+        [ "As of #{snap["day"]}, the last logged snapshot — unverified briefings " \
+          "#{counters["unverified briefings"] || "?"} · projects with 0 concepts " \
+          "#{counters["projects with 0 concepts"] || "?"} (`--full` recomputes these live)" ]
+      end
+
+      def render_full(full)
+        lines = [ "Live from the corpus — unverified briefings #{full["unverified briefings"]}" ]
+        if full["pairing"].empty?
+          lines << "Pairing — the board and the work are in step."
+        else
+          lines << "Pairing — #{full["pairing"].size} finding(s):"
+          full["pairing"].each { |m| lines << "  #{m}" }
+        end
+        if full["unverified"].empty?
+          lines << "Awaiting the owner's read — nothing."
+        else
+          lines << "Awaiting the owner's read (#{full["unverified"].size}):"
+          full["unverified"].each { |m| lines << "  #{m}" }
+        end
+        lines
+      end
+    end
+  end
+end

data/lib/okf/pro/target.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # The bundle root plus the edited path made relative to it.
+    #
+    # `.for` returns nil whenever a check cannot apply — no bundle under the
+    # working directory, a path outside it, not markdown, or behind a dot,
+    # which is the same boundary `okf` itself walks. A file at the repository
+    # root is outside now: README.md and CLAUDE.md are documentation and
+    # instructions, not concepts, and no conformance rule reaches them.
+    # Nil is a real answer here and not a failure: a check that does not apply
+    # has nothing to say, and saying nothing is different from passing something
+    # it could not read. The checks distinguish the two.
+    class Target
+      attr_reader :root, :rel
+
+      def self.for(event)
+        # The file's own ancestry decides which bundle governs it — alone.
+        # There used to be a cwd fallback here, and it was a fence bypass:
+        # containing() would refuse a file inside a nested repository, and
+        # resolve(cwd) — which neither walks nor fences — would re-adopt it
+        # through the physical-prefix check below whenever the session sat
+        # in a root-layout bundle. A file genuinely inside a bundle is
+        # found by its own walk — the walk's classifier accepts a
+        # versioned index or any core file beside a bare one, so even a
+        # mid-bootstrap bundle governs its files; only an index.md truly
+        # alone is ambiguous with a directory index, and the walk refuses
+        # to guess. The fallback could only ever add adoptions the walk
+        # had refused.
+        root = BundleRoot.containing(event.file_path)
+        return nil if root.nil?
+
+        rel = relative(event.file_path, root)
+        return nil if rel.nil? || !rel.end_with?(".md")
+        return nil if rel.split("/").any? { |seg| seg.start_with?(".") }
+
+        new(root, rel)
+      end
+
+      # Relative to the bundle root, or nil when the path is outside it. Made
+      # relative before the dot test on purpose: an absolute path can pass
+      # through `/Users/someone/.local/...` and have nothing dot-prefixed about
+      # the file itself.
+      def self.relative(path, root)
+        return nil if path.to_s.empty?
+
+        full = File.expand_path(path)
+        full.start_with?("#{root}/") ? full[(root.size + 1)..-1] : nil
+      end
+
+      def initialize(root, rel)
+        @root = root
+        @rel = rel
+      end
+
+      # Read once per process. Three PostToolUse checks want the same bundle,
+      # and the read is the expensive part — it is the whole reason they arrive
+      # as one `post-edit` invocation rather than three.
+      def bundle
+        @bundle ||= ::OKF::Bundle::Reader.read(root)
+      end
+
+      def id
+        rel.sub(/\.md\z/, "")
+      end
+
+      def basename
+        File.basename(rel)
+      end
+
+      # A Target holds its root, so every read through it is contained: a
+      # `board.md` that is a symlink out of the bundle is not this bundle's
+      # board, and the gates must not read it as one.
+      #
+      # Raises rather than rescuing. A caller asking a Target to read a named
+      # core file has already established the file exists (`exist?` above), so
+      # a Path::Error here is a real containment failure — and the dispatch
+      # rescue in CLI.run turns any exception into a refusal, which is the
+      # correct answer to "something outside the bundle is pretending to be
+      # inside it".
+      def read(name)
+        Pro.read_contained(root, File.join(root, name))
+      end
+
+      def exist?(name)
+        File.exist?(File.join(root, name))
+      end
+    end
+  end
+end

data/lib/okf/pro/template/gem/.claude/hooks/run

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# The enforcement seam, and the fail-closed wrapper around it.
+#
+# THE CONTRACT: blocking checks fail CLOSED, feedback checks fail LOUD, and no
+# check ever fails SILENT. This file is where the first clause is actually kept.
+#
+# It cannot be collapsed into the checker, and the reason is the whole contract.
+# A script whose interpreter is missing exits 127; a script whose syntax the
+# interpreter rejects exits 1. The hook protocol reads every non-zero code other
+# than 2 as a NON-BLOCKING error — the tool call proceeds. So a Ruby checker
+# structurally cannot refuse on its own absence: something already running has
+# to do it. That is this file's entire job, and it is why settings.json points
+# here and never at `okf` directly.
+#
+# What it refuses with exit 2, each one measured rather than imagined:
+#   no check name;
+#   no `okf` on PATH;
+#   `okf` present but okf-pro not installed (a LoadError out of the deferred
+#     require is a ScriptError, outside every rescue in okf's dispatch — the
+#     process exits 1, which the protocol reads as "proceed");
+#   a syntax error in okf-pro's own plugin.rb (same ScriptError reason, and
+#     nothing Ruby-side runs at all — only this file can catch that one);
+#   a stray `okf` shim on PATH that exits 0 (status alone cannot tell it from a
+#     clean gate, so identity is proved separately — see MARKER below);
+#   any other exit code, which means nothing to the protocol and must not be
+#     allowed to mean "fine".
+#
+# What it does NOT do is exec. The prototype's wrapper did, and an exec'd
+# process's SyntaxError is unreachable: nothing is left running to report it.
+set -u
+
+MARKER='okf-pro-enforcer v1'
+
+check="${1:-}"
+if [ -z "$check" ]; then
+  echo "ENFORCEMENT MISCONFIGURED — .claude/hooks/run was called with no check name; nothing ran." >&2
+  exit 2
+fi
+
+okf_bin="$(command -v okf)" || okf_bin=""
+if [ -z "$okf_bin" ]; then
+  echo "ENFORCEMENT DEGRADED — \`okf\` is not on PATH; no check ran. Run \`gem install okf okf-pro\`, or every edit lands unchecked." >&2
+  exit 2
+fi
+
+# The event arrives on stdin and can only be read once, and this wrapper may run
+# the checker twice (see the bundler fallback below). Buffer it.
+work="$(mktemp -d)" || {
+  echo "ENFORCEMENT DEGRADED — could not create a temp directory to buffer the hook event; no check ran." >&2
+  exit 2
+}
+trap 'rm -rf "$work"' EXIT
+cat > "$work/event" || :
+
+# Bundler's variables make gem discovery bundle-scoped, and okf finds its
+# extensions with Gem.find_latest_files — so inside a bundle that does not name
+# okf-pro, `okf pro` is an unknown command and every gate is off. Restoring
+# the pre-bundler environment fixes that. It is done from bundler's OWN
+# restoration data rather than a hard-coded variable list: the list that matters
+# is RUBYOPT and BUNDLER_SETUP, and BUNDLER_SETUP is recent enough that naming it
+# would be a bet on the adopter's bundler version, on a gem whose floor is 2.4.
+unbundle() {
+  while IFS='=' read -r k v; do
+    case "$k" in BUNDLER_ORIG_*) ;; *) continue ;; esac
+    orig="${k#BUNDLER_ORIG_}"
+    if [ "$v" = "BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL" ]; then
+      unset "$orig"
+    else
+      export "$orig=$v"
+    fi
+    unset "$k"
+  done < <(env)
+}
+
+# One attempt: run the check, capture both streams, and report whether the
+# binary identified itself as the enforcer. Nothing is emitted from here — an
+# attempt that failed to identify is one whose output must not be believed.
+attempt() {
+  "$okf_bin" pro hook "$check" < "$work/event" > "$work/out" 2> "$work/err"
+  rc=$?
+  grep -q "^${MARKER}\$" "$work/err"
+}
+
+if attempt; then
+  :
+elif [ -n "${OKF_PRO_NO_UNBUNDLE:-}" ]; then
+  # Pinned to the first attempt on purpose. The fallback is not free: inside a
+  # bundle, `Gem.find_latest_files` returns nothing at all, so a repo that
+  # deliberately vendors okf-pro through its Gemfile is served ONLY by the
+  # unstripped run, and stripping would lock it out of its own checker.
+  :
+else
+  unbundle
+  attempt || :
+fi
+
+if ! grep -q "^${MARKER}\$" "$work/err"; then
+  # Whatever it did say first, then the verdict — the same order the passing
+  # path uses, so the last line on stderr is always this wrapper's answer.
+  sed "/^${MARKER}\$/d" "$work/err" >&2
+  echo "ENFORCEMENT DEGRADED — \`okf\` did not identify itself as the enforcer, so no check ran. Either okf-pro is not installed (\`gem install okf-pro\`), or something else on PATH answers to \`okf\`. Nothing here has been checked." >&2
+  exit 2
+fi
+
+# stdout is the protocol's own channel — a PreToolUse `ask` decision and the
+# SessionStart banner both travel on it — so it is passed through byte for byte.
+# The prototype's fix for this file captured it in a command substitution and
+# swallowed both: an `ask` became a hard block, and the session banner vanished.
+cat "$work/out"
+sed "/^${MARKER}\$/d" "$work/err" >&2
+
+case "$rc" in
+  0) exit 0 ;;
+  2) exit 2 ;;
+  *)
+    echo "ENFORCEMENT DEGRADED — \`okf pro hook $check\` exited $rc, which the hook protocol reads as non-blocking. Refusing instead: an exit code the gate did not choose is not a verdict." >&2
+    exit 2
+    ;;
+esac

data/lib/okf/pro/template/gem/.claude/skills/okf-pro/SKILL.md

@@ -0,0 +1,233 @@
+---
+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 sense inside this project, the finding
+  that is really a status update.
+* **Someone else wrote it** → `reference/`. Their document, their claim,
+  your summary of it, with the source recorded.
+* **A conclusion of mine, true beyond one piece of work** → `learnings/`.
+* **A term needing a fixed meaning** → `glossary/`.
+* **What happened on a day** → `journal/`.
+
+When two of these fit, the tiebreak is retrieval: file it where you
+would look for it in six months, having forgotten which project it came
+from.
+
+When **none** of them fits, prefer the room that nearly does. Do not
+open a catch-all: a room meaning "everything else" is a blind spot by
+construction — things enter it and nothing enumerates them again — and
+nobody has ever searched for the thing that did not fit.
+
+The five are the starting set, not the closed set. A sixth room is
+earned by an incident rather than anticipated: once the same misfiling
+has actually cost you something, make the room, name it for the
+question it answers rather than for its subject, and link it from
+`index.md` — an unlinked directory is a room nobody can find.
+
+Material you are *mirroring* rather than summarising — a script, run
+instructions, a vendored copy — already has a home in the format: OKF
+§6.3's `references/`. Note the plural: this bundle's `reference/` holds
+your summaries of other people's work, and the two are one character
+apart.
+
+Before minting any name — a concept's title, a tag, a type — read the
+naming policy in `/areas/corpus.md`. It is short, it is the adopter's
+own standard, and a name that collides with what a word already means
+in their domain is a file nobody can search for.
+
+## Rule 1 — Writing is reconciliation
+
+Before a new concept settles — an inbox line promoted, a briefing
+created, a finding recorded — search the bundle for what it collides
+with: `okf search` on the claim's key terms, and read the bodies of
+what comes back — not a glance at titles.
+Three outcomes. It contradicts nothing: file it. It supersedes
+something: correct the loser **now** — title and `description:` first,
+`status: deprecated` on its frontmatter, superseded reasoning into
+`<details>` — because ingestion is the only moment both claims are in
+front of someone and the cost of noticing is at its minimum. The status
+field is the machine-readable half of that move: it is what lets a later
+search see that a collision was already settled instead of re-litigating
+it, and the reconcile gate says so when it fires next.
+
+Or the conflict cannot be settled on the spot: **file it, do not resolve
+it** — one dated line on the board, both sides linked:
+
+```
+- <date> — Resolve: [/reference/a.md] says X, [/glossary/b.md] says Y — noticed while <doing what>
+```
+
+An unresolved contradiction is work. It competes for attention like
+work, and only resolving it takes the line away. Know what this rule
+cannot do: it catches collisions **as well as your search vocabulary
+does, and no better** — which is why it has a second checkpoint:
+whenever any search returns two concepts that disagree, that collision
+gets the same board line, whatever you were looking for. And it is why
+`index.md` curation and `glossary/` naming are load-bearing rather than
+hygiene: the corpus's consistency is bounded by its findability.
+
+## Rule 2 — The day ends with a snapshot, and the delta is the signal
+
+The end-of-day sitting (journal entry + board update, one habit)
+appends one line to `log.md`, last entry under the day:
+
+```
+* **Snapshot**: inbox N (oldest Xd) · in flight k/CAP · waiting N (M past chase) · backlog N · to read N · unverified briefings N · conflicts open N · deadlines within 7d not in flight N · projects with 0 concepts N
+```
+
+The line is mechanical and belongs to `log.md`, not the journal —
+counters are neither hunch nor judgment. Mechanical means derivable:
+`okf pro snapshot .` computes the line, and the stop gate
+refuses one that disagrees with the board it summarises — a counter
+that drifted is a confession that lies. The deadlines field is a
+confessed blind spot: a date due within seven days that no in-flight
+line links is a collision visible before it lands. Its value is the
+comparison with yesterday's line: "+8 inbox, oldest now 6d" is
+information; a standing count is wallpaper, and a warning that is
+always present carries zero information. If a delta deserves a sentence
+of judgment, that sentence goes in the journal, which is where judgment
+lives. And a day too heavy to journal gets the mechanical fallback:
+reconstruct the entry from `log.md` and git history, and say in the
+entry that it was reconstructed — a thin honest record beats a gap that
+reads as a quiet day.
+
+A brand-new bundle ships dateless — an undated `log.md`, an empty
+`journal/`. That is day-zero state, not a defect: never backfill an
+initialization entry or a day nobody worked. The first working day
+creates its own `## <date>` section and first journal entry, and the
+stop gate hands you the exact snapshot line to append.
+
+## Rule 3 — In flight is a budget
+
+At most **5** demands in flight; `board.md` carries `In flight: k/5` at
+the top. Promoting from Backlog requires demoting something — or
+renegotiating the cap, which is allowed, visible, and
+**journal-worthy**, because "the week the cap went to 6" is exactly
+what a review needs and exactly what a silently exceeded cap hides. The
+cap's job is not to make five the right number; it is to make overload
+undeniable on the day it happens. Two exemptions: Deadlines (they come
+due regardless of anyone's budget) and Backlog (captured, not claiming
+attention). One question the budget asks on its own: an in-flight
+demand no journal entry has linked in **5 working days** gets the
+dormancy line — still in flight, or backlog pretending? Either answer
+is fine; holding a slot without moving is not. The session banner asks
+it mechanically, and stays quiet while the journal is younger than the
+window — a bundle in its first week cannot be dormant, only new.
+<!-- rule: okf-pro-dormancy-window -->

data/lib/okf/pro/template/gem/.claude/skills/okf-pro/guides/attribution.md

@@ -0,0 +1,46 @@
+# Attributing what you did not write
+
+Everything in `reference/` is somebody else's claim, and the bundle's
+whole argument is that a claim can be traced back. That is `sources:` — a
+list of what the concept was derived from, each entry with a `resource`
+naming something a reader can follow (a URL, a bundle path) or, when there
+is nothing to follow, the population it came from (`all invoices in
+Q3 2026`).
+
+```yaml
+sources:
+  - id: acme-pricing
+    resource: https://acme.example/pricing
+    title: Acme pricing page
+    author: team:acme-marketing
+    last_modified: 2026-08-01
+```
+
+**Attribute individual claims with footnotes keyed to a `sources[].id`**,
+not with a citations list at the bottom:
+
+```markdown
+Seats are billed annually, with no monthly option.[^acme-pricing]
+```
+
+The label *is* the join key — the reader resolves attribution through the
+matching entry, and never by parsing the footnote's prose. Keyed rather
+than positional because agents rewrite these documents constantly: a
+`sources[0]` misattributes silently the moment the list is reordered,
+while a stable `id` survives it.
+
+Two lint checks hold this up, and both **block** an edit:
+
+* a footnote whose label matches no `sources[].id` and has no definition
+  of its own — the claim points at nothing, which is worse than an
+  unattributed claim because it reads as attributed;
+* a `sources[].resource` naming a bundle path that does not exist.
+
+Neither fires on a concept with no `sources[].id` at all: a bundle that has
+not adopted keyed attribution is not at fault, and an ordinary markdown
+footnote is prose. The moment one source carries an `id`, the join is live.
+
+A source with no `id` is fine when nothing in the body cites it
+individually — the provenance is still recorded. Give it an `id` when a
+sentence needs to point at it.
+