docs(readme): fix unreproducible near-miss advisory example (BUG-003) #4

Merged

anuna-02 merged 0 commits from refs/pull/4/head into main

2026-07-15 05:58:43 +00:00

anuna-02 commented

2026-07-15 05:57:16 +00:00

(Migrated from codeberg.org)

What

Fixes BUG-003: the README's SPEC-005 vocabulary example advertised a
near-miss sibling advisory that could not be reproduced by following the docs.

Running the old snippet verbatim (define ci-green/1 then assert 'ci-green-m2')
prints advisory (inert-family): family ci-green-m2, not the documented
advisory (sibling): family ci-green. The flat atom ci-green-m2 resolves to
its own family via family() CON-402 rule 4, so it is never a sibling of
ci-green-m1; the snippet also never created the r-verified listener it
referred to.

Changes

README — replaced the example with a self-contained, verified sequence:
define → a rule listening on (ci-green ?t) → a proven (review-approved m1)
witness → assert '(given (ci-green m2))', which reproduces
advisory (sibling): family ci-green/1 … did you mean (ci-green m1)? (listener r-verified).
Corrected the vocab sample output to its real rendering.
README — added a note that the advisory is best-effort and daemon-only:
silently absent on a direct-store assert or on the first assert to a theory
after a daemon (re)start (SPEC-005 NFR-402).
bugs/BUG-003 — new entry, status resolved.

Notes

Documentation-only — the runtime was already spec-compliant (the cold-cache
degradation is exactly NFR-402). The optional "warm views at daemon start"
enhancement is noted in the bug as a follow-up, not included here.

Verification

Clean-room run of the exact corrected README commands from an empty
ELEPHANT_HOME: the vocab table and the sibling advisory both reproduce
verbatim.

🤖 Generated with Claude Code

https://claude.ai/code/session_013uvP86ka66MGp1DutJUR6B

## What Fixes **BUG-003**: the README's SPEC-005 vocabulary example advertised a near-miss *sibling* advisory that could not be reproduced by following the docs. Running the old snippet verbatim (`define ci-green/1` then `assert 'ci-green-m2'`) prints `advisory (inert-family): family ci-green-m2`, not the documented `advisory (sibling): family ci-green`. The flat atom `ci-green-m2` resolves to its own family via `family()` CON-402 rule 4, so it is never a sibling of `ci-green-m1`; the snippet also never created the `r-verified` listener it referred to. ## Changes - **README** — replaced the example with a self-contained, verified sequence: `define` → a rule listening on `(ci-green ?t)` → a proven `(review-approved m1)` witness → `assert '(given (ci-green m2))'`, which reproduces `advisory (sibling): family ci-green/1 … did you mean (ci-green m1)? (listener r-verified)`. Corrected the `vocab` sample output to its real rendering. - **README** — added a note that the advisory is best-effort and daemon-only: silently absent on a direct-store assert or on the first assert to a theory after a daemon (re)start (SPEC-005 NFR-402). - **bugs/BUG-003** — new entry, status `resolved`. ## Notes Documentation-only — the runtime was already spec-compliant (the cold-cache degradation is exactly NFR-402). The optional "warm views at daemon start" enhancement is noted in the bug as a follow-up, not included here. ## Verification Clean-room run of the exact corrected README commands from an empty `ELEPHANT_HOME`: the `vocab` table and the sibling advisory both reproduce verbatim. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_013uvP86ka66MGp1DutJUR6B

No reviewers

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

anuna-research/elephant!4

No description provided.

Rows
Columns