Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/decision-fomo-kernel-shape.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,8 +240,9 @@ Split the current non-goal in two:
recommendation may rest on sourced public facts and labelled agent judgment
with or without a book. Explicit discovery reports its universe, filters,
as-of date, material exclusions, and never claims exhaustive coverage. When a
portfolio consequence matters, each candidate is evaluated ephemerally and
only the selected or still-live candidate is rerun persistently.
portfolio consequence matters, each candidate is evaluated ephemerally, and a
persistent rerun requires the user's explicit selection — a standing
recommendation is not one.
- **Market forecasts — judgment, never engine fact.** "This position takes your
semiconductor exposure to 48%" is anchored in the user's record and checkable
now. "NVDA reaches $250" is a forecast and must carry assumptions,
Expand Down
9 changes: 7 additions & 2 deletions docs/development-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -271,8 +271,13 @@ names what actually holds it; where nothing does, the row says so.
(#543) is a second instance, weaker in kind: it checks a shared literal
phrase rather than a list derived from source, because there is no engine
artifact to derive a freeform-answer-shape rule from. Two rules are now
wired this way; a third must-always-land rule forgotten in one entry point
is still caught by nothing.
wired this way. #838 added a gate of a different kind for the same failure:
`README.md` installs the product by symlinking `skills/fomo-kernel/` alone,
so an installed host never receives `AGENTS.md` or anything else at the
repository root — `tests/test_installed_skill_tree.py` reads only that
directory and fails when any of the six non-negotiable boundaries stops
being readable from inside it. A new must-always-land rule forgotten in
one entry point is still caught by nothing.
- Do not trust pattern counts of prohibitions ("N occurrences of *never*").
Most hits describe engine behavior the agent relies on to do *less* work;
deleting them creates work. Read and classify before concluding.
Expand Down
18 changes: 15 additions & 3 deletions docs/expression-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -415,12 +415,24 @@ and references this file. None of them may restate, narrow, or contradict the
pyramid or V/D/C. "Derivation" is what that surface **adds** to §3; an empty
derivation is valid and is the default.

**A shared claim authority is not a derivation.** Three of the conversational
surfaces read `references/research-priors.md` for the same research baseline
(#716), and it adds a shape parameter to none of them: it says what a block may
be *backed by*, never which floor a block sits on or that a block must exist.
The derivation column below is unchanged by that ruling; the file appears in the
last column, where a surface's other keeps live. Its own "An engine fact
dominates a prior" section is the single statement of how far a prior may travel
beside a computed number; the two book-bearing routes carry that sentence
**verbatim** rather than a paraphrase of it, and `tests/test_research_priors.py`
fails on drift — the same mechanism #834 used to put one exemplar on each
surface's generation path.

| Surface | Layout authority | Derivation it adds to §3 | Everything else it keeps |
|---|---|---|---|
| Review card | [output-contract.md](output-contract.md) | The **document incarnation**: keynote + four fixed blocks, in that order, on every committed card. | Module prerequisites, which block the footnote ends. |
| `consider` | `references/trade-consequence.md` | Lead-selection salience order; the answer slots the middle floor may hold; `rule_effects` is never traded away. | What the payload means, the obligation floor. |
| Freeform answers | `references/freeform-answers.md` | None on shape — text-first is a latency default, not a shape. | Proportionate production, reusable engine-backed views. |
| No recorded book | `references/decision-framing.md` | The top sentence is a research-backed baseline when no book exists; the strategy-class map is a middle-floor block set. | Claim boundaries, question heuristics, the invitation set. |
| `consider` | `references/trade-consequence.md` | Lead-selection salience order; the answer slots the middle floor may hold; `rule_effects` is never traded away. | What the payload means, the obligation floor, the research baseline a computed number may be interpreted with. |
| Freeform answers | `references/freeform-answers.md` | None on shape — text-first is a latency default, not a shape. | Proportionate production, reusable engine-backed views, the same research baseline when the question is a decision. |
| No recorded book | `references/decision-framing.md` | The top sentence is a research-backed baseline when no book exists; the strategy-class map is a middle-floor block set. | Claim boundaries, question heuristics, the invitation set; the baseline catalogue it shares with the two routes above. |
| Weekly market read | `references/weekly-market-read.md` | Its one optional question comes after the complete brief, never before it. | What the prototype reads, and what it may not invoke. |

## 7. Enforcement
Expand Down
2 changes: 2 additions & 0 deletions docs/maintainer-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,8 @@ reader-question-chain) while leaving those rows' every other ruling intact.
| Positive decision contract and ephemeral comparison (#825, 2026-08-19) | `AGENTS.md` boundary 5 ↔ `skills/fomo-kernel/SKILL.md` answer shape / candidate comparison ↔ `review.py` `consider --ephemeral` ↔ `answer_provenance.agent_case_claims` / `validate_agent_case` ↔ `schemas/answer-provenance.schema.json` / `schemas/evaluation-challenge.schema.json` ↔ `evaluation_challenge.CASE_REQUIRED` ↔ `references/trade-consequence.md` / `decision-framing.md` / `market-lookup.md` ↔ `evals/judge_trade_answers.py` ↔ `tests/test_answer_provenance.py` / `test_consider.py` / `test_trade_answer_judge.py`. New cases use one `recommendation` labelled `agent_judgment`, non-empty `support`, and optional `counter_case`; the legacy `for`/`against` shape remains readable for append-only history. `--ephemeral` is allowed only against the existing recorded book, computes the identical content-addressed evaluation, reports `append.status=ephemeral`, and never touches `trade_evaluations.jsonl`; rerunning the selected candidate without the flag is the canonical write. Research, counter-cases, unchecked disclosures, questions, and resolution invitations are relevance-driven rather than standing quotas. Numeric authority, provenance coverage, private/local state, execution truth, and canonical persistent writes are unchanged. |
| Permission boundaries and useful-answer freedom (#827, 2026-08-19) | Supersedes the answer-shape portions of #543, #597, #629, #674, and #697 while preserving their integrity work. Reasoning, research, explicit candidate discovery, comparison, recommendation, and materially useful tools or visuals are allowed with or without a recorded book. A book gates only book-derived claims: weights, concentration, cash effects, rule collisions, and state transitions remain engine-owned. Questions, source count, lookup attempts, option count, sentence shape, and presentation form have no universal numeric ceiling; use decision value, material coverage, marginal value, cost, and latency as stopping criteria. `usable_facts_grounding` owns the frozen numeric allow-set; `single_candidate_integrity` owns supplied context, process leakage, and false action claims rather than banning all digits. Exploration stays `consider --ephemeral`; only the user-selected live candidate is rerun persistently, so rejected exploration adds zero canonical evaluation rows. Historical rows above describe why their slices shipped, but their effort ceilings, answer templates, and recommendation bans are not current authority after this row. |
| Deletion-first answer obligations (#830, 2026-08-20) | Supersedes the answer-shape portions of the whitelist era — #479 Wave B cut 2's single `must_state` list, #823's placement-only D-series, and #825's "relevance is governed, placement and form are free" — while leaving every integrity gate those rows built exactly where it was. `engine/evaluation_challenge.py` emits three lists instead of one: `must_state` (the floor), `may_state` (the concentration family and cash — computed, addressed, owed by default on no call), and `machine_state` (`basis.state_version`, never rendered in any register). Its readers: `schemas/evaluation-challenge.schema.json` (additive; new keys are required because the block is computed fresh per call and never stored, and the `must_state` topic enum narrows to match `TOPICS` because `tests/test_evaluation_challenge.py` holds those two as an ordered equality) ↔ `references/trade-consequence.md` "What the answer owes" (which now states a reason per keep and per delete, and defines *stated*: the fact appears with its correct anchor — inline number, table cell, or end-block line all qualify, so fifteen obligations are not fifteen sentences) ↔ `SKILL.md`'s answer shape ↔ `references/freeform-answers.md` rule 4 ↔ `docs/expression-contract.md` D7 ↔ `tools/ux_receipt.py` ↔ `tests/test_evaluation_challenge.py` / `test_consider.py` / `test_expression_contract.py` / `test_interaction_trajectory.py` / `tests/agent/check_expression.py` / `evals/trade_answers/`. **The deletion is of obligations, never of data**: every number is still computed, still anchorable, still citable, and the user can ask for any of it — which is what makes not saying a number this decision does not turn on different from hiding it. **The two silences that could hurt stayed machine-enforced**: `rule_effects` and `required_coverage` are untouched, so a rule the *user* wrote is still named and still refused-for-dropping while the engine's own default threshold became a may-state. **Volume distribution became expression's business** (D7: a fact lives on exactly one floor — opening body, parenthetical beside its number, one end-block line, or not rendered), which §2 had disclaimed and nothing else had claimed; that gap is why fifteen owed facts became fifteen body sentences with every D rule satisfied. The reading-budget rule proposed as V10 in the issue is **not** adopted: a length cap is what #827 had just deleted. The named risk is the other direction — a deciding consequence omitted — and its backstops are the two hard mandates above plus the owner-live `comprehension` verdict, never a checker. |
| Cross-route research baseline (#716, 2026-08-23) | `skills/fomo-kernel/references/research-priors.md` is the single catalogue and the single statement of how far a prior may travel. Its readers: `references/decision-framing.md` (the route that already had it — the baseline is its top sentence) ↔ `references/trade-consequence.md` ("The research baseline, and why it may not fill a gap") ↔ `references/freeform-answers.md` ("The research baseline is available here too") ↔ `docs/expression-contract.md` §6 ↔ `tests/test_research_priors.py`. Four rules. **The catalogue is reachable from every route that answers a decision, not only from the one with no book.** Before this row it was linked by exactly one file, and the user-visible consequence was inverted evidence value: a user with nothing recorded heard that broad diversification is the baseline and that an index label alone does not establish breadth, and the same user, after handing over a book, got weights and concentration and could no longer reach that baseline at all. `test_b_the_catalogue_is_reachable_from_every_route` is what fails when a route's link is dropped, and it walks `SKILL.md → route file → catalogue` rather than asserting the catalogue exists, because a reference nothing names is text nothing loads (the `profile.md` precedent). **An engine fact dominates a prior, and that boundary has one home.** `research-priors.md`'s own "An engine fact dominates a prior" section owns it: a prior may interpret a deterministic result, never replace, substitute for, or fill a gap in one, and it may not invent a cap, an allocation, or a threshold the user has no rule for and the engine did not compute. The two book-bearing routes carry that sentence **verbatim, not paraphrased**, and name the section it comes from: a paraphrase is how five independent phrasings of answer-first happened (#832), and a pointer alone is a boundary the agent has to open a second file to learn. This is #834's answer applied to a rule instead of an exemplar — the same text in three places, made mechanical rather than forbidden, with `test_e_the_engine_fact_boundary_is_one_sentence_in_three_places` failing on any drift and `test_f_reachability_and_boundary_mutations_are_caught` proving it fails. `decision-framing.md`'s "A missing number is never replaced by a general rule" red line stays where it is and gains a pointer: it is the *no-book* form (no computed weight exists at all), and the new section is the form for the routes that do have one. **It is a claim authority, not a derivation.** It adds no shape parameter to any surface, so `expression-contract.md` §6's derivation column is deliberately **unchanged** and the catalogue appears in the last column instead; `freeform-answers.md`'s empty derivation (#832) stays empty and says so in the new section itself. A prior enters an existing block, is subject to §3's increment gate like any other, and a standing paragraph on the value of diversification is the `default_as_insight` ban with a citation stapled to it. **No runtime surface moved**: no engine file, schema, `.json` payload contract, new field, or new engine vocabulary — #716 §1 says the first version needs no runtime schema, and `SKILL.md` is untouched because it already routes to all three route files, which is the whole point of #507's byte budget on the always-loaded pair. Why the row exists: #716's title is "Cross-route evidence-backed decision priors" and the shipped implementation (#727) wired exactly one route, so the issue's own §4 — the boundary that makes the other routes safe — had never been written down anywhere. |
| The six non-negotiable boundaries reach the installed host (#838, 2026-08-23) | `README.md` installs the product by symlinking `skills/fomo-kernel/` alone, so `AGENTS.md` — and any rule stated only there — does not exist on an installed host. The floor's six boundaries therefore live twice: `AGENTS.md` "## Non-negotiable boundaries" (the checkout floor) ↔ `skills/fomo-kernel/SKILL.md` (each boundary stated in the section that exercises it; the privacy boundary as its own "Private data stays local" section, key sentences verbatim — except the anything-public example list, deliberately re-cast for the installed audience as "a shared card, an example, a bug report" where the floor names the maintainer's issues/PRs/fixtures/receipts) ↔ `skills/fomo-kernel/references/agent-boundaries.md` (the routed may/may-not contract `SKILL.md` names as holding throughout; carries the CLI whitelist, the hand-assembly ban, and the third-party/cloud privacy sentence). No text runtime surface under `skills/fomo-kernel/` (every `.md`/`.json`/`.html`/`.txt`) may cite `AGENTS.md` for a rule — its reader may not have the file; `references/freeform-answers.md` stating the card-privacy default instead of citing "AGENTS.md invariant 4" is the pattern. `.py` comments under `engine/` and `tools/` sit outside that scan deliberately: boundary 1 keeps an installed agent out of engine internals, so those citations are maintainer-facing rationale, not instructions an installed reader follows. `tests/test_installed_skill_tree.py` reads **only** `skills/fomo-kernel/` and fails when a boundary's statement retreats to the repository root — every other suite reads the checkout, which is exactly why #838 shipped unseen. The #507 byte budget split with it: `SKILL.md` has its own ceiling (the whole always-loaded surface of an installed host) and `AGENTS.md` its own (the checkout-only floor), because one budget over a pair that exists only in a checkout let the floor's bytes squeeze the installed contract to zero headroom — the pair sat at exactly 16384 bytes when #838 was found. |

Date product assumptions when using them for prioritization. Reconfirm assumptions that are several weeks old or contradicted by new evidence.

Expand Down
Loading
Loading