ontology-rebuild

Rebuild the semantic overlay for files that have changed since the last resolution pass. The scope argument is optional — if omitted, processes all dirty files. If provided, can be code, docs, or a specific repo name to limit scope.

Note: all repo paths in bash blocks below are rooted at $REPO_ROOT to avoid cwd drift when the skill is invoked from a worktree or child-repo subdirectory (#149).

This skill resolves the SEMANTIC OVERLAY only. For the generated structural index (ontology/structural/llms.txt, code-graph.json), run the generator: PYTHONPATH=.claude/lib python3 -m ontology_gen . --out ontology/structural/ and the aggregator: PYTHONPATH=.claude/lib python3 -m ontology_gen.aggregate .. The lifecycle skills (/session-start Step 3b, /wave-wrapup Step 12b) do this automatically.

Context — generate-structural + curate-semantic model (C×T2, #820/#862)

The ontology uses two cooperating layers, each with its own update path:

Layer	Contents	Update path
Semantic overlay	domain.yaml, services.yaml, conventions.md, repos/*.yaml, hand-edited *.md	This skill (/ontology-rebuild) — reads checksums.json dirty entries, reconciles against code
Structural index	ontology/structural/llms.txt, code-graph.json, cross-repo-graph.json	Generator (ontology_gen + ontology_gen.aggregate) — regenerated wholesale, never hand-edited

This skill (the Resolver) and the Change Tracker hook operate exclusively on the semantic overlay:

• Change Tracker (hook) — auto-updates ontology/checksums.json on every Edit/Write to hand-curated files. Sets last_tracked hash.
• Change Resolver (this skill) — reads dirty entries from checksums, processes files, updates semantic overlay + auto-updatable docs. Sets last_resolved = last_tracked.
• Librarian (/ontology-librarian) — read-only reference, surfaces BOTH layers; staleness check for each.

A file is "dirty" when last_tracked != last_resolved in checksums.json.

Scope: the SEMANTIC OVERLAY only — NOT the generated structural layer (#857, #820/C×T2)

This skill (the Resolver) and the Change Tracker hook operate on the hand-curated semantic overlay: ontology/domain.yaml, ontology/services.yaml, ontology/conventions.md, ontology/repos/*.yaml, and other hand-edited *.md. These are the files a human edits and that therefore need dirty-tracking + resolution.

The structural layer at ontology/structural/ is out of scope: it is GENERATED by an owned generator (#855), regenerated wholesale rather than hand-resolved, so it is always-current-by-regeneration. The tracker hook skips it (see ontology_tracker.py SKIP_PATTERNS), so it will never appear as a dirty entry here — and /ontology-rebuild must never hand-edit it. To refresh the structural layer, re-run its generator, not this skill. (Background: this is the C×T2 decision that also softened Hook 15 from a hard pre-edit block to advisory — structural context is now current-by-regeneration, not stale.)

Code is the final arbiter of truth

This skill derives the ontology and the auto-updatable docs FROM the code. When the code and a doc/ontology entry disagree, the code wins: update the ontology/doc to match the code — never edit the code to match a stale doc. Source code (.py/.ts/.tf/.yaml config/schemas/…) is read first (step 2 orders code → docs → high-level-docs precisely so code is resolved before anything derived from it); READMEs, CLAUDE.md, inline docs, and the ontology files are downstream artifacts that must be brought into agreement with it. Recommend-only docs (high-level-docs/, architecture diagrams) are flagged for human review rather than auto-rewritten, but the conflict is still reported with code as the reference. This is the canonical statement of the org convention in ontology/conventions.md § Ontology: code is the arbiter of truth, enforced PR-side by the advisory doc-freshness gate (.claude/lib/doc_freshness.py, #768).

Instructions

1. Read checksums and identify dirty files

REPO_ROOT="$(git rev-parse --show-toplevel)"
cat "$REPO_ROOT/ontology/checksums.json"

Build a list of all files where last_tracked != last_resolved. If no dirty files exist, report "Ontology is up to date — no dirty files" and stop.

If scope argument is provided, filter:

• code — only source code files (.py, .ts, .tsx, .js, .jsx, .go, .yaml, .yml, .toml, .json, .tf, .hcl)
• docs — only documentation files (.md, .rst, .txt)
• {repo-name} — only files under that repo's directory (e.g., noorinalabs-isnad-graph/)

2. Process files in order: code → docs → high-level-docs

Process dirty files in this order:

1. Source code files — read each file, extract entities, services, APIs, patterns, data models
2. Auto-updatable docs (READMEs, CLAUDE.md, inline docs) — check for drift from code, update if needed
3. Recommend-only docs (high-level-docs/, engineering docs, mermaid diagrams, architecture documents in any repo) — read for intent and purpose, note recommendations but do NOT modify

For each file:

• Read the file content
• Determine which ontology file(s) it affects:
  • Domain entities/relationships → ontology/domain.yaml
  • Services, APIs, data stores, infrastructure → ontology/services.yaml
  • Conventions, patterns, tooling → ontology/conventions.md
  • Repo-specific internals → ontology/repos/{repo-name}.yaml
• Update the relevant ontology file(s) with extracted knowledge
• If the file is an auto-updatable doc that has drifted from code, update it

3. Cross-reference and consistency

After processing all dirty files:

• Check for orphaned entities (referenced but not defined)
• Check for stale references (defined but the source file no longer contains them)
• Verify cross-repo integration points are consistent between services.yaml and repo files

4. Update checksums

For each processed file, set last_resolved = last_tracked and resolved_at = now in checksums.json.

Also update checksums for any ontology files that were modified during this pass.

5. Report

**Ontology Rebuild Complete**

**Files processed:** {count}
**Ontology files updated:**
- domain.yaml: {entities added/updated/removed}
- services.yaml: {services added/updated/removed}
- conventions.md: {sections updated}
- repos/{name}.yaml: {changes}

**Docs auto-updated:** {list of docs that were updated to match code}

**Recommend-only changes (requires human review):**
- {file}: {recommended change}

**Consistency issues found:** {list or "None"}

6. Commit ontology changes

Stage and commit all ontology changes and any auto-updated docs. Use the Standards & Quality Lead identity (Aino Virtanen) for ontology commits:

cd "$REPO_ROOT" && \
  git add ontology/ && \
  git -c user.name="Aino Virtanen" -c user.email="parametrization+Aino.Virtanen@gmail.com" \
      commit -m "ontology: rebuild — {summary of changes}"
# Also add any auto-updated docs before committing.

Docs update policy

Doc type	Location	Action
READMEs	Any repo	Auto-update to match code
CLAUDE.md	Any repo	Auto-update to match code
Inline code docs	Any repo	Auto-update to match code
high-level-docs/	noorinalabs-main	Read-only — recommend changes
Engineering docs	Any repo (architecture.md, diagrams, etc.)	Read-only — recommend changes
Mermaid diagrams	Any repo	Read-only — recommend changes

What remains manual

• Recommend-only doc updates require human review and decision
• Ontology structure changes (adding new top-level categories) should be discussed first
• Removing entities requires confirmation — prefer marking as deprecated
• The structural index is never resolved here — to refresh it, run the generator directly or use /session-start Step 3b / /wave-wrapup Step 12b which do it automatically:

  PYTHONPATH=.claude/lib python3 -m ontology_gen . --out ontology/structural/
  PYTHONPATH=.claude/lib python3 -m ontology_gen.aggregate .