50%

§00 walking skeleton fitness harness

Goal

Prove the thinnest end-to-end seam: a committed, rule-derived fitness probe corpus served by a live fitness subcommand, red at baseline, with live-baseline regeneration and self-shrinking freeze semantics. The measuring stick ships before any capability.

Implementation Sketch

  • Probe corpus: versioned JSON under intel_repo (queries/fitness/), each probe = {id, cypher-or-subcommand, expected reading, rationale, rule-family link}. Initial six probes per the grill: burden-seam (callees lookup_burden resolves TypeRegistry::burden + BurdenRegistry::lookup_builtin; writers-of burdens map returns register_user_burden), resolved-CALLS ratio (live count, never baked), platform-domain presence, ori :CodeComment presence, cluster-2 blocker inventory (cpg_resolver filtered_reason), plan-doc pollution ratio (SZZ L7).
  • cmd_fitness lands as a thin reader per the D2 writer/reader split (query_graph.py commands dict); wrapper dispatch untouched (generic pass-through); help text + drift-test triad (KNOWN/PLANNED/LIVE) updated same commit.
  • Baseline: ArchUnit-style self-shrinking freeze (frozen red probes auto-unfreeze as they green); SonarQube clean-as-you-code framing (gates score new/changed surface, never absolute totals).
  • Schema note: schema.cypher is NOT auto-applied by refresh — the section applies constraints explicitly (shipped-analog lesson).

Spec References

  • intel_repo/neo4j/query_graph.py (commands dict, D2 reader style); intel_repo/tests/test_rules_file_query_blurbs_drift.py (KNOWN/PLANNED/LIVE triad); scripts/intel_query/01-bootstrap.sh + 05-dispatch.sh; .claude/rules/impl-hygiene.md STRUCT-99 (walking skeleton), FLOW-43 (no baked counts)

Work Items

  • Define and validate separate versioned schemas for the committed fitness probe corpus and generated baseline. Commit probes for the burden-registration seam, resolved-CALLS ratio, platform-domain presence, Ori comment-node presence, cluster-2 resolution blockers, and plan-doc pollution ratio, plus a resolved cluster positive control. Give every probe a stable ID, live query or subcommand, comparator, exact expected targets or negative control where applicable, rule-family link, and evidence-bearing pass/fail/unavailable/stale outcome contract. Keep mutable graph counts out of corpus literals; keep observed normalized values and frozen failing IDs only in the generated baseline, with a deterministic regeneration path.
  • Implement one validated fitness reader/evaluator and a thin cmd_fitness in intel_repo/neo4j/query_graph.py: load the schema-bound corpus and baseline, execute live Neo4j readings, evaluate probes once, emit stable JSON with graph freshness plus per-probe state and evidence, and support explicit baseline regeneration. Register cmd_fitness in the existing commands dict, advertise it in scripts/intel_query/01-bootstrap.sh help, leave the generic scripts/intel_query/05-dispatch.sh pass-through unchanged, and add fitness directly to KNOWN_SUBCOMMANDS so LIVE_SUBCOMMANDS remains derived.
  • Tests: corpus and baseline schema acceptance/rejection; exact-target, negative-control, and ratio comparators; pass/fail/unavailable/stale states with evidence; deterministic atomic regeneration, baseline round-trip, and self-shrinking freeze behavior; a live-query integration pin showing the burden probe reports the confirmed missing outgoing targets without modifying compiler fixtures; CLI dispatch smoke with EXPECTED_DISPATCH_SMOKE_COUNT updated; help/KNOWN/LIVE drift tests green; and the real wrapper JSON envelope stable.
  • After contract tests pass, run graph status and invariant verification, execute scripts/intel-query.sh fitness —json through the real wrapper-to-Python-to-Neo4j path, and atomically persist a deterministically ordered red baseline containing normalized observed values, freshness evidence, and frozen failing probe IDs. Verify that unavailable or stale facets remain explicit rather than green, greened frozen probes automatically leave the freeze, and new or changed surfaces are gated without freezing mutable absolute totals.

Fresh intel (regenerated)

The section is correctly placed as the walking skeleton, and the live graph already supplies an honest red baseline. The graph cannot resolve either outgoing call from lookup_burden, contains no platform-domain symbols, contains no platform comments, has unresolved cluster-2 indirections, contains no READS_FIELD/WRITES_FIELD edges, and currently has no INTRODUCED_IN edges from which to compute the SZZ plan-doc-pollution ratio. The resolved-CALLS snapshot is 42,063 resolved edges against 20,031 unresolved targets, a live ratio of 0.6774084452604117.

Two implementation-sketch assumptions must be corrected before editing:

  1. scripts/intel_query/05-dispatch.sh is already a generic pass-through to query_graph.py at lines 219-239. fitness needs a cmd_fitness reader plus the Python commands entry, help text, and test/drift pins; a command-specific wrapper branch would duplicate dispatch and violate SSOT-14 / LEAK:duplicated-dispatch.
  2. fitness is absent from both KNOWN_SUBCOMMANDS and PLANNED_UNWIRED_SUBCOMMANDS. Do not implement a fictional “move” from the planned set. Add it directly to KNOWN_SUBCOMMANDS; LIVE_SUBCOMMANDS derives from that set automatically. This direction satisfies SSOT-01/SSOT-22 and avoids another pinned-enumeration drift.
  3. Keep the corpus, generated baseline, and query execution responsibilities distinct. The corpus declares probe identity/query/comparator/rule link; the generated baseline records observed values and frozen failing probe IDs; cmd_fitness reads and evaluates both. Validate structured files at load time per SSOT-38.
  4. Record stale or absent facets as explicit probe readings, not empty success. The first baseline must preserve why a probe is red so section 01 can later enrich envelopes without rewriting the fitness contract.

[JOIN] The source shows lookup_burden directly calls BurdenRegistry::lookup_builtin and TypeRegistry::burden, while the graph reports zero outgoing CALLS from it. The probe is therefore not speculative: it pins a confirmed graph false negative at the exact compiler seam later section s-16f6a8a2 must make bidirectionally traversable.

VERDICT: Proceed with the fitness harness as a thin, validated reader over committed data, but do not add a special wrapper dispatch path or edit compiler burden code. This is the STRUCT-99 walking-skeleton obligation, constrained by SSOT-* and LEAK:duplicated-dispatch.

DIG DEEPER

scripts/intel-query.sh status
scripts/intel-query.sh plan-status intel-graph-deepening
scripts/intel-query.sh cypher "MATCH (s:Symbol {repo:'ori'}) WHERE s.name='lookup_burden' OPTIONAL MATCH (s)-[:CALLS]->(c:Symbol {repo:'ori'}) RETURN s.qualified_name, collect(c.qualified_name)"

(full dossier: walking-skeleton-fitness-harness—s-a61c303c.intel.md)