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:
parent
956714594d
commit
1260fac154
12 changed files with 532 additions and 43 deletions
64
CHANGELOG.md
64
CHANGELOG.md
|
|
@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
|
||||
## [Unreleased]
|
||||
|
||||
## [0.7.0] — 2026-09-09
|
||||
|
||||
The first screen an agent reads, the three shapes of request the skill answers,
|
||||
and one defect that made the command the first screen recommends build a worse
|
||||
bundle than the command it claims to be.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`okf project` built a bundle two rules behind `okf build`.** `cli.build`'s
|
||||
Python signature defaulted `keep_table_heading` and `sheet_section_rows` to
|
||||
`False` while argparse defaulted both to `True`; `project.create` calls
|
||||
`build()` as a function and passes no flag list, so it read the signature.
|
||||
Measured on a five-document folder: `okf project` wrote **15 concepts / 30
|
||||
files** where `okf build` on the same folder wrote **26 / 52**, and the whole
|
||||
difference was in the priced spreadsheet — the document a question about price
|
||||
has to reach. The invariant test that was supposed to catch this could not:
|
||||
it compared `project.create` against the same `build()` function, so both
|
||||
sides carried the same wrong value, and its two fixture documents had neither
|
||||
a table nor a sheet. Both gaps are now tests: one compares the signature's
|
||||
defaults against argparse's, the other builds a document whose concept count
|
||||
actually moves with the two flags. After the fix the two paths are byte-equal
|
||||
on that folder (`diff -rq`, 0 differences).
|
||||
|
||||
### Added
|
||||
|
||||
- **A first screen for a reader who has not used this before**, agent or human:
|
||||
what it is in one sentence, one install line, two commands, and the three
|
||||
shapes of request. The phase-status paragraph that used to open the README
|
||||
moved down to `## What this library is`; nothing was deleted.
|
||||
- **Three modes in the consumption skill**, stated in the template, the
|
||||
instantiated skill and the generator:
|
||||
- **Question** — as before, the default.
|
||||
- **Hypothesis** — decomposed into premises and answered **per premise** as
|
||||
`confirmed` / `refuted` / `undecidable-from-bundle`, three literals with no
|
||||
fourth value. A premise whose excerpt is real but does not carry the
|
||||
conclusion is `[sourced-not-sufficient]` on **that premise**, not on the
|
||||
whole answer: four premises and one weak source is three answers and one
|
||||
gap, and reporting it as one refusal throws the three away.
|
||||
- **Task that produces a document or a paragraph** — every claim in the
|
||||
written artefact carries `(bundle_id, concept_id)`, the excerpt's `sha256`,
|
||||
its `title` and whichever `source_*` keys it has; an ungrounded paragraph is
|
||||
**written and marked**, never dropped; and the cut (`considered`,
|
||||
`withheld`, `delivered`) is declared inside the document, because the
|
||||
document travels without the chat.
|
||||
The five markings are untouched — the modes add no sixth.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The generated skill states relative paths where it can.** In the layout
|
||||
`okf project` writes, the commands are now `okf consume .okf/<id>` and
|
||||
`okf check --skill .claude/skills/<id>-consume/SKILL.md`, runnable from the
|
||||
project root — which is where `okf project`'s own closing line tells the
|
||||
reader to start `claude`. A path outside the project root stays absolute on
|
||||
purpose: `../../..` is not more portable, only harder to read. The two
|
||||
absolute paths a generated skill carried are now zero, measured with a query
|
||||
shown capable of finding first — O5's published "4 → 0" used `grep -c "^/"`
|
||||
against paths indented by two spaces, which could not have matched either way.
|
||||
- **One tag is pinned everywhere.** `README.md` pinned `v0.4.0` on its install
|
||||
lines and `v0.6.0` further down, and `llms.txt` pinned `v0.4.0`; an agent
|
||||
reading from the top installed a tag without `okf project`. All install lines
|
||||
now name `v0.7.0`, and the earlier tags are kept as a labelled history
|
||||
section rather than as commands. `llms.txt` gained the `okf project` form and
|
||||
a pointer to the Claude Code section.
|
||||
|
||||
## [0.6.0] — 2026-09-08
|
||||
|
||||
The first tag since `v0.5.0a2`, so everything that had accumulated as
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue