Tier 2: XSD → SKOS vocab seeder (scripts/seed_vocab_from_xsd.py)

[pedroanisio]

Context

static/schemas/ was vendored as a test fixture (see tests/verify_xsd_fixture.py). The schemas also contain rich domain vocabularies (DDD: AggregateRoot, BoundedContext, Entity, Repository; IEEE 29148: StakeholderRequirement, SystemRequirement, etc.) that could materially strengthen our concept_graph plugin's labeling quality.

Today, L3 concepts are produced purely from identifier splitting — purely lexical. After this work, a bundle of a DDD-style codebase would surface concepts tagged with cbml3:conceptKind = domain-primitive and cbml3:broaderCollection = ddd_v3_ontology, unlocking MCP queries like "show me every DDD aggregate root in this repo."

Scope

Add scripts/seed_vocab_from_xsd.py that:

1. Walks static/schemas/*.xsd and parses each with xml.etree.ElementTree (or lxml if added).
2. Extracts <xs:element name="…">, <xs:complexType name="…">, <xs:attribute name="…">, and <xs:simpleType name="…"> declarations.
3. Normalizes names (split camelCase, lowercase, dedup) per the existing concept_graph splitter rules so the extracted terms align with what splitter produces from identifiers.
4. Writes new SKOS collections into codebase_mapper/vocab/ — one per source XSD:
   • ddd_v3_ontology (from ddd/v3_0_0/*.xsd)
   • ieee_29148_ontology (from ieee_29148.xsd)
   • ieee_12207_ontology (from ieee_12207.xsd)
   • iec_5055_ontology, eic_ontology, c4_v2_ontology, ast_ontology
   • python_metacode_ontology, ddd_python_bridge_ontology, bridge_ast_treesitter_ontology
5. Each concept tagged with:
   • skos:inScheme <collection>
   • cbml3:conceptKind "domain-primitive"
   • cbm:source pointing at the XSD path (provenance)
6. Idempotent — re-running over the same input produces byte-identical output.

Subtasks

• Implement scripts/seed_vocab_from_xsd.py
• Decide YAML vs Turtle output format (existing vocab uses YAML — match that)
• Add tests/verify_vocab_xsd_seed.py — runs seeder against a small fixture, asserts known concepts present (e.g. aggregate_root, bounded_context)
• Update docs/vocabulary.md — section "Seeded collections" describing source + regeneration procedure
• Update pyproject.toml [tool.setuptools.package-data] so static/schemas/*.xsd and the seeded YAMLs ship with the wheel (if external consumers need to re-run the seeder)
• Update README.md ## Controlled vocabulary section to mention seeded collections

Blockers

• License review for vendored standards XSDs in static/schemas/ #1 license review — IEEE/IEC schemas must be cleared before redistributing in seeder output (concept names are likely a thinner derivative than the schemas themselves, but worth verifying).

Acceptance

After this lands, python scripts/seed_vocab_from_xsd.py produces N new vocab YAMLs and python scripts/run_l3.py over any DDD-style codebase tags AggregateRoot-shaped identifiers with cbml3:broaderCollection ddd_v3_ontology.

Tier classification

Per session analysis: this is Tier 2 — the genuinely proposition-strengthening move. Tier 1 (fixture wiring) already landed.

[pedroanisio]

Blocked by #1.

The XSD → SKOS extraction in this issue will redistribute concept names derived from copyrighted standards (IEEE 12207, IEEE 29148, IEC 5055). Although extracting element names is a thinner derivative than redistributing the schemas themselves, the license posture must be cleared in #1 before this work can ship publicly.

Local development and fixture-only use are unaffected — the seeder can be implemented and tested against the project-internal schemas (DDD, AST, C4, bridge/, python-metacode/) without depending on the standards files. Plan to gate the IEEE/IEC seeded collections behind whatever disposition #1 produces (keep / remove / replace with synthetic equivalents).

[pedroanisio]

Backing PR landed: commit 5f478c7 — the fixture this work will consume is now present under static/schemas/ (16 XSDs deduped from 27 source paths).