feat(query): cgis init-ontology — auto-proposed patterns.yaml (#174)

[zaebee]

Summary

Closes #174 (roadmap #179 P0 adoption blocker — pairs with the merged #178 trust guard).

Ships cgis init-ontology (CLI) + cgis_init_ontology (MCP, read-only): the measure-then-label proposer that turns drift from "hand-write YAML first" into one command — ingest → propose → drift passes green by construction.

• New src/cgis/query/ontology_init.py: domain discovery (auto-descent + --depth), fingerprint per domain, DriftScorer as the fitter (zero new scoring math — proposed tolerances measured + margin ceil-2dp are comparable to later drift runs)
• Per domain: nearest template + runner-up + measured fit in comments; honest no-fit branch (>0.5 → hygiene-only, no forced labels); below-min_nodes / edge-less → hygiene-only with reasons; hygiene entries also get measured tolerances (cyclic domains round-trip)
• CLI refuses overwrite without --force; MCP returns YAML text and writes nothing (sidesteps the S2083 path-write taint class)
• The self-graph now self-labels: api→pure_utility, cli→dispatcher, extractors/guardian/query→layered_dag, resolver→pipeline_stage, storage→pure_utility — drift on the proposal: exit 0, zero EMPTY rows

Review fix-rounds folded in

1. discover_domains empty-level bug: a never-branching lineage descended into [] — now yields its deepest id (adversarial reviewer catch, hand-traced regression test)
2. Hygiene profile-mismatch: hygiene-only tolerances were scored with profile=None while the yaml emitted the detected profile → v1 weight divergence broke the round-trip on cyclic domains (opus reviewer reproduced 0.67 > 0.53); fix threads the emitted profile through, regression test uses a real IMPORTS cycle

⚠️ One conscious ratchet re-baseline

cgis.query tolerance 0.18 → 0.20: ontology_init.py joining the domain raised its measured drift to 0.19. Documented in the yaml comment; same rationale class as #199's extraction re-baseline (the domain legitimately grew, not a gaming of the gate). The drift tool flagged its own new feature — working as intended.

Test Plan

• 846 tests (15 module + 3 CLI + 2 MCP + self-graph round-trip incl. margin=0.0 stress), mypy strict, interrogate 99.5%
• Round-trip divergence channels adversarially traced (profile/params/hygiene-merge/v1-v2 routing/cross-domain) — none remain
• Lane contract: cli.py / mcp_server.py pure appends; cgis_find_symbol from main untouched
• SDD: 5 tasks × review (2 fix-rounds) + final holistic review READY FOR PR
• guardian + colleague review

🤖 Generated with Claude Code

[zaebee]

/guardian review

[github-actions]

Summary: Found 2 critical logic bugs in ontology_init.py (never-branching lineage and auto-descent loop) that cause incorrect domain discovery. 2 tests mask these bugs by expecting the wrong output. No type safety, ontology, or contract issues detected.

---

🤖 mistral-medium-latest · 25,011 prompt + 1,075 completion = 26,086 tokens · graph 3/7 files (43%)

[gemini-code-assist]

Code Review

This pull request implements the cgis init-ontology CLI command and the read-only cgis_init_ontology MCP tool to auto-propose a starter patterns.yaml from a measured graph. The changes introduce a new module src/cgis/query/ontology_init.py for domain discovery and template fitting, append the new commands to the CLI and MCP server, and add extensive unit and round-trip tests. The review feedback suggests two key improvements: parsing the static YAML header once at the module level to avoid redundant parsing during template fitting, and replacing rstrip(".") with removesuffix(".") to prevent unintended character stripping.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[zaebee]

Review — strong PR, one blocking gate + a couple of nits

Read the core (ontology_init.py), the CLI/MCP appends, the ratchet, and both fix-rounds. Dogfooded the round-trip on the self-graph: ingest → init-ontology → drift returns exit 0, "All domains within tolerance" — "green by construction" verified end-to-end, zero EMPTY rows. The DriftScorer-as-fitter (zero new scoring math) is the right call — it's exactly why the round-trip can't diverge. MCP being read-only (returns YAML, writes nothing) cleanly sidesteps the S2083 taint class. 👏

🔴 Blocking — Sonar gate fail: new_duplicated_lines_density 4.6% > 3%

The dominant source is the three hygiene branches in _domain_entry (ontology_init.py:265-282): each repeats the same _hygiene_score → _ceil2 → profile.append → drift_tolerance.append block, only the reason string differs. Collapsing them is both the dedup fix and a clarity win (preserves exact output ordering):

    hygiene_reason: str | None = None
    if fp.node_count < min_nodes:
        hygiene_reason = f"# below min_nodes ({fp.node_count} nodes) — census too small to label"
    elif fp.edge_count == 0:
        hygiene_reason = "# no intra-domain edges — nothing to fit"
    elif best > _NO_FIT_THRESHOLD:
        hygiene_reason = f"# no template fits (best: {best_name} at {best:.2f})"

    if hygiene_reason is not None:
        tolerance = _ceil2(_hygiene_score(fp, prefix, scorer, profile) + margin)
        lines.append(f"    profile: {profile}{profile_suffix}")
        lines.append(f"    drift_tolerance: {tolerance:.2f}  {hygiene_reason}")
    else:
        comment = (
            f"# measured ≈ {best:.2f} via init-ontology"
            f" (runner-up: {runner_name} at {runner:.2f}) — ratchet down over time"
        )
        tolerance = _ceil2(best + margin)
        lines.append(f"    expected_pattern: {best_name}")
        lines.append(f"    profile: {profile}{profile_suffix}")
        lines.append(f"    drift_tolerance: {tolerance:.2f}  {comment}")

If that alone doesn't clear 3%, the secondary contributor is the per-file node-factory blocks (each new test file defines its own identical Node(...) builder) — consolidating them into one shared test helper would close the rest.

🟡 Non-blocking nits

1. _fit_templates:182 re-parses _DEFAULT_ONTOLOGY_HEADER via yaml.safe_load on every domain just to read patterns.keys(). The template-name list is constant — parse once (module-level or hoisted into propose_ontology and threaded in). Negligible now, but it's O(domains) redundant YAML parses.
2. Round-trip at margin=0.0: tolerance becomes _ceil2(score), which can equal the score exactly on a 2dp boundary. The guarantee then rests on the drift gate being <= (not <). You have the margin=0.0 stress test so it's empirically fine — just confirming it's intentional, since a future flip of the gate comparator would silently break it.

Verified / liked

• Both fix-rounds are real and tested: empty-level lineage (discover_domains:332-336) and profile-threading through _hygiene_score (the cyclic-domain round-trip).
• The cgis.query 0.18→0.20 ratchet is documented with rationale — same conscious-re-baseline class as #199's extraction bump (domain legitimately grew). Note it's an increase, so when #151 (ratchet-enforce CI) lands it'll need the carve-out comment it already has.

Once the gate's green this is good to go from my side.

[zaebee]

/gemini review

[gemini-code-assist]

Code Review

This pull request implements the cgis init-ontology CLI command and cgis_init_ontology MCP tool to automatically propose a starter patterns.yaml configuration from a measured graph. It introduces the ontology_init.py module, which handles domain discovery and template fitting, alongside comprehensive unit and round-trip tests. The review feedback highlights three improvement opportunities: validating that the depth parameter is a positive integer in both the domain discovery logic and the CLI option, and updating the CLI summary table's type check to format integer tolerances consistently with floats.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[zaebee]

Round 2 — gate green, all prior items addressed ✅

Re-reviewed after the updates; Sonar quality gate is now OK (new-code duplication back under 3%). Re-ran the dogfood on the current head: ingest → init-ontology → drift still exit 0, "All domains within tolerance", and --depth 0 is now correctly rejected (x>=1).

Prior items:

• 🟡 nit #1 (_fit_templates re-parsing the header per domain) — ✅ fixed: _TEMPLATE_NAMES parsed once at module load behind an isinstance(..., dict) guard. Clean.
• 🔴 duplication gate — ✅ resolved. For the record, the dominant CPD source was the per-file test fixtures (the 9814a80 chain-db dedupe did it), not the _domain_entry branches I led with — good call consolidating those.
• 🟡 nit #2 (round-trip at margin=0.0 resting on a <= gate) — fine as-is, the stress test covers it; flagged only for future awareness.

New this round (verified, all correct):

• discover_domains depth validation — typer --depth min=1 plus a library-level ValueError for depth≤0 that the MCP path funnels into the ❌ medium. Guarded at both layers. 👍
• rstrip(".") → removesuffix(".") — strictly more correct (single-suffix vs char-class strip), even though current inputs can't trigger the difference.
• _render_init_summary int-or-float tolerance guard — harmless defensiveness for hand-edited yaml.

One optional, non-blocking: the three hygiene branches in _domain_entry:270-287 are still near-identical (only reason differs). Now that the gate's green this is purely a clarity call — collapse via a single hygiene_reason path if you like, or keep the explicit ladder for readability. Your call.

LGTM — good to merge from my side. 🟢

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[zaebee]

Re: round 2 — the optional dedup taken (36c614b): the hygiene triplet collapses to a reason ladder + single emission block (−15/+10 lines, output byte-identical — the determinism test pins it). Thanks for the two-round pass and the empirical re-verification.

🤖 Generated with Claude Code