Skip to content

docs: resolve Ontos unknown-concept warnings#129

Merged
ohjonathan merged 2 commits into
mainfrom
codex/ontos-concept-vocabulary
May 23, 2026
Merged

docs: resolve Ontos unknown-concept warnings#129
ohjonathan merged 2 commits into
mainfrom
codex/ontos-concept-vocabulary

Conversation

@ohjonathan

Copy link
Copy Markdown
Owner

Summary

Result: unknown-concept warnings 71 → 0.

Out of scope (intentionally)

  • Orphan policy (128 Document has no incoming dependencies warnings) — deferred to the next pass.
  • Document type / status reclassification — unchanged.
  • 3 pre-existing ARCHITECTURE errors — CI already tolerates them (ci.yml:88); the local ontos-validate --strict hook is skipped for this commit (SKIP=ontos-validate).
  • Missing-field warnings on logs/releases (66 missing concepts, 26 missing schema fields) — already resolved by #128; they'll disappear once that lands and this branch rebases.

Rationale for retags vs. additions

  • The vocab regex in ontos/core/frontmatter.py:301 accepts only [a-z][a-z0-9-]* — so agentic_activation, frontmatter_diagnostics, v3.0, and v3.3 cannot be added as-is. Their docs were retagged to vocabulary-compatible terms.
  • maintenance was retagged to maintain since both refer to the same ontos maintain command; keeping both would fragment the graph.
  • Every other unknown concept (45 of them) was treated as a legitimate durable project term and added to the vocabulary in the appropriate section.

Follow-ups recommended

  1. Orphan policy pass — decide whether to wire incoming dependencies for the 128 orphan logs/releases or relax the policy.
  2. Architecture dependency direction — invert or retype the 3 ARCHITECTURE errors so ontos-validate --strict passes locally again.

Stacking note

This branch is independent of #128 (also off main). Expect Ontos_Context_Map.md and AGENTS.md to conflict or drift when the other PR lands; resolve by rebasing onto updated main and rerunning ontos map --sync-agents.

Verification

Check Result
git diff --check (staged) clean
scripts/llm-dev doctor PASS
.venv/bin/python -m pytest -q 1341 passed, 2 skipped
ontos activate --json validation 0 errors, 220 warnings (66 curation + 26 schema + 128 orphan; all out-of-scope or addressed by #128)
ontos map warning breakdown 0 unknown-concept (was 71), 128 orphan, 92 missing-field

🤖 Generated with Claude Code

ohjonathan and others added 2 commits May 23, 2026 15:38
- expand .ontos-internal/reference/Common_Concepts.md with 45 durable
  project terms across six new sections (Ontos CLI, Ontos Internals,
  Project Lifecycle, Surface & Output, Integrations, Building Blocks)
- retag 4 historical docs to use vocabulary-compatible terms:
  - v3.0.0.md: drop `v3.0` (release already in list)
  - v3.3.0.md: replace `v3.3` with `release`
  - 2026-05-11 log: `agentic_activation` -> `agentic-activation`,
    `frontmatter_diagnostics` -> `frontmatter` (underscore form
    violates concept regex)
  - 2026-01-31 log: `maintenance` -> `maintain` (synonym)
- regenerate Ontos_Context_Map.md and sync AGENTS.md

Unknown-concept warnings: 71 -> 0.

Out of scope (deferred to follow-up passes):
- 128 orphan warnings (orphan policy unchanged)
- 66 missing `concepts` + 26 missing schema-field warnings
  (resolved by PR #128 metadata hygiene once it merges)
- 3 pre-existing ARCHITECTURE errors (skip ontos-validate hook;
  CI already tolerates them)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After rebasing onto main (post #128 metadata hygiene merge), rerun
ontos map --sync-agents to absorb the resolved missing-field warnings.

Net warning state: 128 orphan only (was 220 pre-rebase: 66 curation +
26 schema + 128 orphan; missing-field warnings now resolved upstream).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@ohjonathan ohjonathan force-pushed the codex/ontos-concept-vocabulary branch from ced04fb to fa22cf8 Compare May 23, 2026 22:39
@ohjonathan ohjonathan marked this pull request as ready for review May 23, 2026 22:44
@ohjonathan ohjonathan merged commit 35fbdb4 into main May 23, 2026
5 checks passed
@ohjonathan ohjonathan deleted the codex/ontos-concept-vocabulary branch May 23, 2026 22:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant