feat(readme,skill,cli): the first screen an agent reads, three modes, and one flag that made two builds

`okf project` built a bundle two rules behind `okf build`. `cli.build`'s
signature defaulted `keep_table_heading` and `sheet_section_rows` to `False`
while argparse defaulted both to `True`, and `project.create` calls `build()`
as a function. Measured on a five-document folder: 15 concepts / 30 files
where `okf build` wrote 26 / 52, the whole difference in the priced sheet --
the document a question about price has to reach. The invariant test could not
see it: it compared `project.create` against the same function, and its two
fixture documents had neither a table nor a sheet. Both gaps are tests now,
and the two paths are byte-equal on that folder (`diff -rq`, 0 differences).

README opens with what / one install line / two commands / the three shapes of
request; the phase-status paragraph moved down, nothing deleted. One tag is
pinned everywhere: README pinned v0.4.0 on its install lines and v0.6.0 below,
llms.txt pinned v0.4.0, so an agent reading from the top installed a tag
without `okf project`.

The skill states three modes -- question, hypothesis (per premise, `confirmed`
/ `refuted` / `undecidable-from-bundle`), and a task producing a document
(source per claim in the artefact, an ungrounded paragraph written and marked
rather than dropped, the cut declared inside the document). The five markings
are untouched.

Generated skills state relative paths in the project layout: `okf consume
.okf/<id>` and `okf check --skill .claude/skills/<id>-consume/SKILL.md`,
runnable from where `okf project` tells the reader to start `claude`. Two
absolute paths to zero, measured with a query shown capable of finding first --
O5's published "4 -> 0" used `grep -c "^/"` against paths indented by two
spaces.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-09 18:12:02 +02:00
commit 1260fac154
12 changed files with 532 additions and 43 deletions

View file

@ -48,6 +48,59 @@ and the cut; it decides nothing about the question.
when you were handed a bounded window, is the denominator failure below with
extra steps.
## Modes
Three shapes of request, one discipline. Which one you are in is decided by what
was asked, never by what the payload happened to contain.
### Question
Answer it from the delivered excerpts, mark every claim, and stop. The default.
### Hypothesis
A hypothesis is a claim someone wants tested, not a question. **Decompose it
into its premises first and answer PER PREMISE** — a single verdict over the
whole hypothesis hides which part the bundle actually covered.
Each premise gets exactly one of three literals:
| Verdict | Use when |
|---|---|
| `confirmed` | the delivered excerpts carry the premise |
| `refuted` | the delivered excerpts carry its contradiction |
| `undecidable-from-bundle` | neither, within what was delivered |
These three are literals, like the five markings: no fourth value, no
"partly confirmed", no translation. A premise whose excerpt is real but does not
carry the conclusion is marked `[sourced-not-sufficient]` **on that premise**,
not on the whole answer — a hypothesis with four premises and one weak source
has three answers and one gap, and reporting it as one refusal throws the three
away.
The hypothesis-level verdict is then stated as a consequence of the per-premise
ones, with its reasoning shown. It is `derived`, never `extracted`.
### Task that produces a document or a paragraph
Some requests want a written artefact — a note, a section, a table of
requirements — rather than an answer in chat. The artefact is held to the same
rule as an answer, in the artefact itself:
- **Every claim carries its source in the document**: `(bundle_id, concept_id)`,
the excerpt's `sha256`, its `title`, and whichever `source_*` keys that
excerpt has. A footnote, a parenthesis or a trailing line all work; leaving it
out because "the chat already said it" does not — the document is what gets
read, forwarded and quoted, and it travels without the chat.
- **A paragraph with no ground is written, not dropped.** Mark it
`[sourced-not-sufficient]` and leave it standing where it belongs, saying what
was asked for and what the bundle did not carry. A silently omitted section is
the denominator failure with a nicer surface: the reader cannot see the hole,
so they read a complete document.
- **Declare the cut inside the document**, not only in chat: `considered`,
`withheld` and `delivered`, plus the bundle ref. The three counts and the ref
are what let a later reader tell whether the document is still current.
## Markings
Every claim carries exactly one of these five literals, plus a pointer to the

View file

@ -76,6 +76,59 @@ library's line-oriented parser can read, so no tier could be derived honestly),
the delivered cap), `over_budget_after_knapsack` (it fitted alone but not
alongside the set that was chosen).
## Modes
Three shapes of request, one discipline. Which one you are in is decided by what
was asked, never by what the payload happened to contain.
### Question
Answer it from the delivered excerpts, mark every claim, and stop. The default.
### Hypothesis
A hypothesis is a claim someone wants tested, not a question. **Decompose it
into its premises first and answer PER PREMISE** — a single verdict over the
whole hypothesis hides which part the bundle actually covered.
Each premise gets exactly one of three literals:
| Verdict | Use when |
|---|---|
| `confirmed` | the delivered excerpts carry the premise |
| `refuted` | the delivered excerpts carry its contradiction |
| `undecidable-from-bundle` | neither, within what was delivered |
These three are literals, like the five markings: no fourth value, no
"partly confirmed", no translation. A premise whose excerpt is real but does not
carry the conclusion is marked `[sourced-not-sufficient]` **on that premise**,
not on the whole answer — a hypothesis with four premises and one weak source
has three answers and one gap, and reporting it as one refusal throws the three
away.
The hypothesis-level verdict is then stated as a consequence of the per-premise
ones, with its reasoning shown. It is `derived`, never `extracted`.
### Task that produces a document or a paragraph
Some requests want a written artefact — a note, a section, a table of
requirements — rather than an answer in chat. The artefact is held to the same
rule as an answer, in the artefact itself:
- **Every claim carries its source in the document**: `(bundle_id, concept_id)`,
the excerpt's `sha256`, its `title`, and whichever `source_*` keys that
excerpt has. A footnote, a parenthesis or a trailing line all work; leaving it
out because "the chat already said it" does not — the document is what gets
read, forwarded and quoted, and it travels without the chat.
- **A paragraph with no ground is written, not dropped.** Mark it
`[sourced-not-sufficient]` and leave it standing where it belongs, saying what
was asked for and what the bundle did not carry. A silently omitted section is
the denominator failure with a nicer surface: the reader cannot see the hole,
so they read a complete document.
- **Declare the cut inside the document**, not only in chat: `considered`,
`withheld` and `delivered`, plus the bundle ref. The three counts and the ref
are what let a later reader tell whether the document is still current.
## Markings
Every claim carries exactly one of these five literals, plus a pointer to the