100%

explain-idx CLI verb + north-star pins + docs

Goal

Ship the ori explain idx <n> <file> CLI verb (sibling to the env knob, one tracer SSOT), the north-star regression pins, and the permanent doc surfaces. Closes the plan: the diagnostic is discoverable, pinned, and documented.

Implementation Sketch

The CLI verb and ORI_TRACE_IDX both dispatch ONE tracer entry (no duplicate logic). The north-star pin runs the tracer on both struct and enum fixtures asserting the generic-vs-concrete divergence + drop-glue attribution. Docs land on exactly one canonical surface per tool.

Spec / Rule References

compiler/oric/src/commands/; .claude/rules/diagnostic.md; compiler_repo/diagnostics/README.md; .claude/rules/tooling-first.md §4 (one canonical doc surface); .claude/rules/diagnostic-ux.md (regression pin is the gate).

Test Strategy

North-star pin: tracer on Wrap<Wrap<int>> AND Holder<Holder<int>> surfaces the field/payload generic-leaf divergence + _ori_drop$<param-idx> attribution as one DAG. ori explain idx --help works (exit 0).

Work Items

  • Add the ori explain idx <n> <file> CLI verb in compiler/oric/src/commands/ dispatching the tracer (sibling to the ORI_TRACE_IDX env knob; both route to one tracer entry, SSOT); --help documents it.
  • North-star regression pin: the tracer on Wrap<Wrap<int>> AND Holder<Holder<int>> surfaces the generic-vs-concrete divergence + drop-glue attribution as ONE legible DAG (this IS the plan-wide functional criterion’s probe).
  • Doc surfaces (permanent-diagnostic discipline per tooling-first.md §4): .claude/rules/diagnostic.md entry, compiler/oric/src/debug_flags.rs doc comment, compiler_repo/diagnostics/README.md row; one canonical surface per tool.
  • North-star regression pin (this IS the plan-wide functional criterion’s probe): the tracer surfaces the generic-vs-concrete divergence + drop-glue (_ori_drop$<param-idx>) attribution as ONE legible DAG on BOTH the Wrap<Wrap<int>> (struct) AND Holder<Holder<int>> (enum-in-enum) nested-generic fixtures (positive legs), AND, as the mandatory negative control, asserts a clean monomorphic type yields a single consistent concrete chain with NO generic-leaf-divergent node (the north-star gate’s second leg; proves the diagnostic discriminates true divergence from clean monomorphization, not flags everything). Pin the verb surface too: ori explain idx --help exits 0 (feature-independent); run the consumer/drop-glue attribution leg under --features llvm (the non-llvm consumer_attribution returns an empty edge set).

Fresh intel (regenerated)

{ “schema_version”: 1, “target”: { “kind”: “plan-section”, “ref”: “idx-provenance-diagnostic/s-52f6e148” }, “generated_at”: “2026-06-28T11:14:58.645828+00:00”, “graph_state”: { “head_sha”: “8340d7a0”, “last_code_import_at”: “2026-06-28T11:10:43.329Z”, “embedding_stale”: false, “insights_stale”: false, “cpg_stale”: false }, “surfaces”: {}, “summary”: “intel-package[plan-section:idx-provenance-diagnostic/s-52f6e148] agent-authored dossier”, “degraded”: false, “dossier”: { “objective_symbols”: [], “tiers”: {}, “agent_authored”: true, “constrained_symbols”: [ “substitute_in_pool”, “set_resolution” ], “difficulty”: { “class”: “routine”, “research_online”: false, “research_mode”: “auto”, “signals”: [], “plan_dir”: “/home/eric/projects/ori_lang/plans/idx-provenance-diagnostic” } } }

(full dossier: cli-and-docs—s-52f6e148.intel.json)