🗺️ Roadmap: priorities from multi-repo dogfooding (#170–#178)

[zaebee]

🗺️ cgis roadmap — distilled from real-world dogfooding (2026-06-11)

This consolidates the 9 issues filed after running cgis on 4 repos of deliberately different topology, so the work is grounded in observed failure modes, not speculation.

Dogfooding corpus

Repo	Topology	What it stressed
Ownima backend	layered, package-per-domain	real cross-module import cycles; IDOR via impact analysis
httpx	flat, one-file-per-concern	intra-module cycle artifacts; pattern mislabeling
click	dynamic CLI, src/ layout	high unresolved; silent zero-match; "shapeless" modules
sqlalchemy	large, deeply-nested	scale; multi-level domains; quotient layer (in progress)

---

P0 — without these, drift can't be adopted / trusted

• Add cgis init-ontology: auto-propose patterns.yaml from measured graph #174 init-ontology — auto-propose patterns.yaml (measure-then-label). Blocker for adoption: drift is a no-op on a fresh repo until someone hand-writes YAML. Hand-labeling also caused real mistakes (httpx._api/_decoders mislabeled → false criticals).
• cgis_drift: zero-match / no-signal domains report 'clean' instead of 'empty' (silent mis-targeted ontology passes green) #178 zero-match guard — a fqn_prefix matching 0 nodes returns clean/0.0. Blocker for trust: a mis-targeted ontology (e.g. click.* vs real src.click.*) reports 100% green while measuring nothing. A CI gate must fail loudly here.
• cycle_ratio: split import-cycles (real smell) from intra-module call-cycles (benign); flat repos give false criticals #176 split import- vs intra-module cycles — cycle_ratio {max:0} fires on benign intra-file class cohesion (httpx: 8/10 domains false-critical) while correctly catching real import cycles (Ownima services/dependencies). Without the split, drift is unusable as a gate on flat/single-module repos.

P1 — correctness & signal quality

• cgis_drift: hygiene-gate breaches (cycles) should force critical; per-domain tolerance vs global max_drift precedence #170 status semantics — hygiene-gate breaches (cycles) must force critical (currently stay warning); clarify global max_drift vs per-domain drift_tolerance precedence (global silently overrides the specific).
• cgis_drift: report fit-quality (nearest-template residual) + domain coverage; surface 'no template fits' #177 fit-quality / residual report — expose nearest-template + residual + coverage of unbound modules. Turns "is the alphabet complete?" into a measured number; flags genuine "no template fits" (click.utils 0.33/0.33/0.33, httpx._content).

P2 — turn the graph into a linter / agent substrate

• Add reachability/coverage audit primitive (authz coverage, layering, validation gaps) #172 authz-reachability audit — "which ROUTE_HANDLERs never reach an AUTHORIZES/ownership check?" Found the Ownima IDOR manually; baking it in makes cgis a security linter. Leverages the existing AUTHORIZES edge type.
• trace_flow / analyze_impact: add JSON output (real FQNs) for agent/CI use #171 JSON output for trace_flow / analyze_impact — Mermaid-only today; structured FQN edge lists enable set-diff queries (the authz sweep) and are more token-efficient for agents.
• Add cgis_find_symbol (partial name → FQN); error on zero-match FQN #173 find_symbol (name → FQN) — agents must currently guess FQNs; pairs with cgis_drift: zero-match / no-signal domains report 'clean' instead of 'empty' (silent mis-targeted ontology passes green) #178's closest-prefix suggestions.

P3 — operational ergonomics

• Incremental / auto ingest: keep graph.db fresh without manual re-ingest #175 incremental / auto ingest — keep graph.db fresh without manual re-ingest; lazy-ingest on first query; staleness signal. Removes the "did you ingest?" footgun. Important for the MCP-server / CI-action distribution form.

---

Suggested sequencing

1. Add cgis init-ontology: auto-propose patterns.yaml from measured graph #174 + cgis_drift: zero-match / no-signal domains report 'clean' instead of 'empty' (silent mis-targeted ontology passes green) #178 together (authoring + safety) — makes drift usable & trustworthy for newcomers.
2. cycle_ratio: split import-cycles (real smell) from intra-module call-cycles (benign); flat repos give false criticals #176 + cgis_drift: hygiene-gate breaches (cycles) should force critical; per-domain tolerance vs global max_drift precedence #170 — make the gate correct across topologies.
3. cgis_drift: report fit-quality (nearest-template residual) + domain coverage; surface 'no template fits' #177 — self-reported completeness.
4. trace_flow / analyze_impact: add JSON output (real FQNs) for agent/CI use #171 → Add reachability/coverage audit primitive (authz coverage, layering, validation gaps) #172 / Add cgis_find_symbol (partial name → FQN); error on zero-match FQN #173 — agent/linter substrate (JSON first, it unblocks the rest).
5. Incremental / auto ingest: keep graph.db fresh without manual re-ingest #175 — ergonomics for the distributed forms.

Cross-refs: #170 #171 #172 #173 #174 #175 #176 #177 #178

[zaebee]

🔀 Two-session lane split (worktree-isolated, to avoid merge conflicts)

We've been running two parallel Claude sessions on this repo. To keep them conflict-free, both work in git worktrees off fresh main, partitioned by subsystem so file footprints don't overlap. Cross-review + gemini on every PR.

Lanes (file-level isolation)

Lane	Owns these files	Backlog
A — Drift / Census / Ontology	query/{drift,drift_service,fingerprint,quotient,triads,analyzer}.py, docs/ontology/*	#170, #176, #177, #182, #186, #174, #147, #149/#150/#146
B — Core / Infra	extractors/*, resolver/*, storage/sqlite_store.py, pipeline.py	#117, #183, #111, #112, #175, residual #185
MCP/CLI ergonomics (owned by one lane at a time)	query/engine.py, query/fqn.py + traversal regions of cli.py/mcp_server.py	#171, #173, #165, #192, #148
Guardian (independent dir, either lane as context-switch)	guardian/*	#181, #154, #155, #126, #94

The one contention surface: cli.py + api/mcp_server.py

Both lanes append commands/MCP tools here. Rule that's worked empirically (#178 drift-region vs traversal-region auto-merged):

1. Each lane edits only its own region of these files (append a focused function; don't touch the other's command/tool).
2. Second-to-merge rebases: git pull main into the worktree before finalizing, re-run the gate.
3. The MCP/CLI ergonomics issues are owned by a single lane at a time, so cli.py/mcp_server.py are never edited concurrently by both.

Already shipped under this model (2026-06-12)

Lane B: #116 (decompose PythonExtractor, #191), #194 extractor fixes (#195), #185 no-op short-circuit (#193). Lane A: #178 drift empty/no_signal (#196). Zero merge conflicts.