Skip to content

docs: promote domain glossary as review baseline (+ package docstring realign)#4

Merged
JasonJarvan merged 13 commits into
mainfrom
docs/glossary_baseline_and_init_docstring
Jun 30, 2026
Merged

docs: promote domain glossary as review baseline (+ package docstring realign)#4
JasonJarvan merged 13 commits into
mainfrom
docs/glossary_baseline_and_init_docstring

Conversation

@JasonJarvan

@JasonJarvan JasonJarvan commented Jun 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Change description

Port the domain terminology glossary onto Raven as the team-review baseline, plus a package-docstring realignment. Two commits:

  1. docs: realign the raven/__init__.py docstring to the current engine layout. It still listed the pre-spine layout (context/, sentinel/, skill_forge/, cron/, memory/, skills/); now it reads context_engine/, proactive_engine/ (Sentinel + Scheduler), memory_engine/skill_forge/, with the base-runtime list trimmed to the modules that actually originated from nanobot.
  2. docs: add the domain glossary as the review baseline: CONTEXT.md + CONTEXT-MAP.md (repo root) and ui-tui/CONTEXT.md. ~39 Runtime terms + 7 TUI terms; ~30 confirmed accurate against current code. The Bus cluster is flagged under-revision -> Spine; the gap-scan open items are summarized in CONTEXT-MAP "Terms under review".

The glossary content was grilled out and reviewed on GitLab; this is its first landing on GitHub, with all everclaw references renamed to raven and the GitLab review-process references neutralized to GitHub (PR / main).

Glossary review workflow (this branch is the integration branch)

This PR's branch is the staging branch for the glossary review:

  1. Each term-owner installs the grill-with-docs skill.
  2. Read the gap-scan review brief (assignment + findings).
  3. Branch off this PR branch, review your assigned terms (grill where useful), and open a PR back into this branch with your refinements.
  4. Review happens directly on those per-owner PRs.
  5. Approved per-owner PRs merge into this branch.
  6. When the review completes, this branch merges into main.

Owner handles are git-author identifiers, not verified GitHub usernames; left unlinked to avoid mentioning the wrong account.

Type of change

  • Document
  • Bug fix
  • New feature
  • Others

Checklists

Development

  • Lint rules pass locally
  • Automated tests covering modified code pass

Docs-only (glossary + a package docstring); no runtime or test impact.

Code review

  • Pull request has a descriptive title and context useful to a reviewer

Sheng Zhao and others added 6 commits June 29, 2026 11:43
@claude
docs: realign package docstring to current engine layout
af55a56 
The raven/__init__.py docstring listed the pre-spine module layout
(context/, sentinel/, skill_forge/, cron/, memory/, skills/). Realign
it to the current engine layout: context_engine/, proactive_engine/
(Sentinel + Scheduler), memory_engine/skill_forge/, and trim the
base-runtime list to the modules that actually originated from nanobot.

Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
@claude
docs: promote domain glossary (CONTEXT) as team-review baseline
f5db32e 
Add the domain terminology glossary as the team-review baseline:
CONTEXT.md + CONTEXT-MAP.md at the repo root and ui-tui/CONTEXT.md for
the TUI context. ~39 Runtime terms + 7 TUI terms; ~30 confirmed accurate
against current code. The Bus cluster is flagged under-revision -> Spine;
the gap-scan open items are summarized in CONTEXT-MAP "Terms under review".

Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
@0xKT @claude
docs(context): replace Bus cluster with Spine + add Agent Core missin…
f3ae2f1 
…g terms

Replace the stale Bus section (Message Bus / Event Bus) with the current
Spine vocabulary, verified against raven/spine/ (7 live files). The old
types (InboundMessage, OutboundMessage, BusEvent) no longer exist in code.

New Spine terms: Spine, Lane, TurnRequest, Deliverable (= RunnerEvent),
OriginPools.

Add 4 missing Agent Core terms: Agent Loop, Turn Runner, Agent Hook,
Subagent — all verified against live module entry points.

Minor stale-reference fixes: Channel / Routing Tag / TUI-RPC avoid note
(Bus → Spine references); EvalEngine expanded to name the three AgentHook
implementations.

Co-authored-by: Claude (claude-sonnet-4-6) <noreply@anthropic.com>
@JasonJarvan
Merge pull request #6 from EverMind-AI/docs/glossary_spine_agent_terms
2ace467 
docs(context): replace Bus cluster with Spine + add Agent Core missing terms
@userName20260323 @claude
docs(glossary): add Consolidator term + fix Profile file casing
b400322 
Add the Consolidator term (memory_engine/consolidate/) to the CONTEXT.md Memory section and fix the Profile backing-file casing to user.md; drop Consolidator from the CONTEXT-MAP proposed-missing list.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@JasonJarvan @claude
docs(glossary): correct skillforge, add plugin and skill hub terms
7d1ecaa 
Rewrite the SkillForge term to match the actual retrieval/injection module (three-source weighted RRF; distillation lives in the EverOS pipeline). Add Skill Hub and the Plugin / Plugin Registry terms. Resolved against the Consolidator term landed earlier; Profile backing-file casing kept as user.md.

Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
@userName20260323 userName20260323 mentioned this pull request Jun 30, 2026
Merged
10 tasks
Sheng Zhao and others added 7 commits June 30, 2026 07:12
@claude
docs: add domain-terms rule to CLAUDE.md pointing at the glossary
c907e0a 
Add section 6 (+ summary-table row): consult the CONTEXT-MAP.md glossary
before naming a domain concept, use the canonical term, and define a newly
coined term in the matching CONTEXT.md in the same change (definition
verifiable against the code, not guessed).

Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
@userName20260323 @claude
docs(glossary): complete agent/context/eval/templates/tokenwise terms
56d0b4f 
Add the remaining domain terms for the agent, context, eval, templates, and tokenwise areas. Merged on top of the Spine/Agent Loop additions and the package docstring + CLAUDE.md domain-terms rule already on the baseline.

Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
@claude
docs: generalize PR-description language rule to "no other languages"
52179b1 
In CLAUDE.md section 3.7, replace "no Chinese" with "no other languages"
and drop the Chinese-specific translate-don't-paste tail. The rule now
reads as a general English-only constraint for PR descriptions.

Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
@claude
docs: generalize English-only rules from Chinese-specific to language…
b5bc09c 
…-agnostic

Sweep CLAUDE.md so the English-only constraints read as general
"no other languages / non-English" rules rather than singling out Chinese
(comments, commit subject/body, path names, self-check grep prose). The
full-width-punctuation examples and the CJK-detecting grep regex are kept
as-is; the bad-commit example strings stay as illustrations.

Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
@shallyan @claude
docs: correct everos glossary entry to reflect memory-backend role (#47)
9ffe76c 
## Change description

> Owner review of the **EverOS** glossary term (assigned to @yan.xiao in
the
> 2026-06-28 glossary gap-scan). Refines the entry in `CONTEXT.md` ->
`### Memory`
> and merges back into the review baseline branch
`docs/glossary_baseline_and_init_docstring`.

The baseline entry read:

> EverOS: An external memory system installed as a built-in tool in
Raven.

Verified against the code, this misstates the role on two counts:

- **Primary role is a memory backend, not "a tool".** It ships as a
bundled
plugin (`raven/plugin/memory/everos/raven-plugin.toml`:
`id=everos-memory`,
`bundled=true`, `enabled_by_default=true`) contributing a
`memory_backends`
factory `everos`. The `understand_media` tool is a *secondary*
contribution of
  the same plugin, not the headline.
- **"External system" is misleading.** The name refers to the external
pip
package `EverMind-AI/EverOS` (`pyproject.toml`: `everos[multimodal]`);
the
  in-tree `raven/plugin/memory/everos/` code is only a thin adapter that
  delegates to it.

Revised entry: a default bundled memory-backend plugin providing
dual-track
semantic recall — user track (episodes/profiles, injected into the `#
Memory`
segment) and agent track (skills/cases, one of SkillForge's three
sources at RRF
weight 0.9) — plus the `understand_media` multimodal-parsing tool.

Note: the adjacent terms touched by EverOS (SkillForge, Skill Hub, the
`# Memory`
segment) were cross-checked and are accurate; `skillForge.everos` is a
real config
key (`raven/config/loader.py`, `update.py`, `raven.py`), so the
SkillForge entry's
reference to it is correct and needs no change.

cc @sheng.zhao for review.

## Type of change
- [x] Document

## Related issues (if there is)

> Glossary finalize (EVE-55)

## Checklists

### Development

- [ ] Lint rules pass locally
- [ ] Application changes have been tested thoroughly
- [ ] Automated tests covering modified code pass

### Security

- [ ] Security impact of change has been considered
- [ ] Code follows security best practices and guidelines

### Code review

- [x] Pull request has a descriptive title and context useful to a
reviewer. Screenshots or screencasts are attached as necessary

Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
@ypflll @claude
docs: correct skillforge + tui glossary terms vs code (#50)
9d8f756 
Contributor review (gap-scan §2/§6) of the terms I touch — SkillForge
(memory_engine/skill_forge/) and the TUI (ui-tui/) — against current
code.

SkillForge:
- backend is the pluggable MemoryBackend (EverOS is the typical plugin),
not a hardcoded "EverOS memory backend"
- retirement is not implemented: retire_confidence /
retirement_idle_days are unwired config placeholders, not a
confidence-floor soft-delete

TUI:
- StatusRulePane -> Status Bar: exported component is StatusRule,
placement via StatusBarMode (top|bottom|off); there is no "Pane"
- Overlay: list the real overlayStore kinds (RPC-driven + user-toggled);
FPS is a separate component, not an overlay-store kind

## Summary

<!-- What changed, and why? -->

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

<!-- List the exact commands you ran and the result. -->

- [ ] Relevant tests pass locally
- [ ] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

- [ ] Security impact considered
- [ ] Backward compatibility considered
- [ ] Rollback path is clear for risky changes

## Related Issues

<!-- Fixes #123, closes #123, or N/A -->

Co-authored-by: yaopengfei <yaopengfei@yaopengfeideMacBook-Pro.local>
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
@JasonJarvan
Merge branch 'main' into docs/glossary_baseline_and_init_docstring
a8faf1f
@JasonJarvan
JasonJarvan merged commit 303558f into main Jun 30, 2026
6 of 7 checks passed
@JasonJarvan
JasonJarvan deleted the docs/glossary_baseline_and_init_docstring branch June 30, 2026 08:19
Kendrick-Song added a commit that referenced this pull request Jul 22, 2026
@Kendrick-Song @claude
fix(*): address cr feedback on cold-start import pr
ecd02a9 
- Move _everos_server.py from raven/cli/ to raven/plugin/memory/everos/
  _server.py to fix plugin->cli layering violation (CR #1)
- Split HTTP timeout: client default 60s (recall/health), memorize
  add/flush per-request 360s (CR #2)
- Defer backend.start() to post-handshake background task in TUI so
  first render is not blocked by server startup (CR #3)
- Remove unused app_id/project_id from ImportSession and scanner
  (CR #4)
- Add note on per-source-unit checkpoint granularity (CR #5)
- Add fcntl file lock to prevent concurrent server spawn race (CR #6)
- Fix loguru %s format to {} in state.py (CR #7)
- Fix docstring step numbering (CR #8)
- Remove redundant Table import in status_cmd (CR #9)

Co-authored-by: Claude (claude-opus-4-6) <noreply@anthropic.com>
Kendrick-Song added a commit that referenced this pull request Jul 22, 2026
@Kendrick-Song @claude
fix(*): address cr feedback on cold-start import pr
5b2fe81 
- Move _everos_server.py from raven/cli/ to raven/plugin/memory/everos/
  _server.py to fix plugin->cli layering violation (CR #1)
- Split HTTP timeout: client default 60s (recall/health), memorize
  add/flush per-request 360s (CR #2)
- Defer backend.start() to post-handshake background task in TUI so
  first render is not blocked by server startup (CR #3)
- Remove unused app_id/project_id from ImportSession and scanner
  (CR #4)
- Add note on per-source-unit checkpoint granularity (CR #5)
- Add fcntl file lock to prevent concurrent server spawn race (CR #6)
- Fix loguru %s format to {} in state.py (CR #7)
- Fix docstring step numbering (CR #8)
- Remove redundant Table import in status_cmd (CR #9)

Co-authored-by: Claude (claude-opus-4-6) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@JasonJarvan @0xKT @userName20260323 @shallyan @ypflll