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
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue