Merge next into main for 0.28.0 release

[mohanagy]

Summary

• Merge the current next line into main for the next stable release.
• Includes strict runtime-proof benchmark gating, public TypeScript explain-runtime receipts, benchmark-suite hardening, and agent/retrieval fixes.
• Brings the checked-in 6/6 legacy public TypeScript explain-runtime full_win receipts into the stable branch.

Notes

• This PR should merge before the stacked release metadata PR.
• Release metadata, version bump, README, and changelog updates are kept in the follow-up PR so the release commit is easy to review.

Verification

• CI on the merged PR fix: complete proof-backed public explain-runtime full-win rows #520 was green across Ubuntu/macOS/Windows on Node 20/22.
• Release PR will run package/version/docs verification separately.

Summary by CodeRabbit

• New Features

  • Added runtime proof validation framework for benchmarks, including obligation-based evidence assessment across multiple repositories.
  • Extended benchmark suite with scoped workspace support (graphRoot) for monorepo configurations.
  • Implemented isolated execution profiles for reproducible benchmark runs with fail-fast authentication checks.

• Documentation

  • Updated benchmark methodology with guidance on repository scoping, execution behavior, and isolation mode.
  • Expanded benchmark results documentation with new public "explain-runtime" trials across multiple repositories.
  • Refined claims and evidence mapping with stricter validation requirements.

• Bug Fixes & Improvements

  • Fixed file-stem collision handling in code extraction for better identifier stability.
  • Enhanced TypeScript compiler options discovery per workspace subdirectory.
  • Improved Next.js convention detection for nested workspace layouts.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Benchmark receipts, runtime-proof contracts, isolation behavior, and graph/extraction plumbing were updated together. The PR also refreshes explain-runtime benchmark artifacts and tests for multiple repos.

Changes

Benchmark runtime-proof and suite wiring

Layer / File(s)	Summary
Docs and receipt refresh docs/benchmarks/suite/README.md, docs/benchmarks/suite/methodology.md, docs/benchmarks/suite/repos.json, docs/benchmarks/suite/runtime-proof.json, docs/benchmarks/suite/results/... , docs/claims-and-evidence.md	Benchmark docs, claims guidance, runtime-proof config, and generated receipt artifacts are updated for the newer warm-cache explain-runtime runs.
Suite manifest and isolation wiring docs/benchmarks/suite/isolation/run-isolated.sh, src/infrastructure/benchmark/suite.ts, tests/unit/benchmark-suite.test.ts, tests/unit/benchmark-suite-isolation-docs.test.ts	Repo manifests, isolation launcher behavior, and benchmark suite workspace preparation are extended for scoped graph roots, CLI shims, and isolated Claude profile handling.
Runtime-proof contracts and retrieval src/contracts/context-pack.ts, src/contracts/retrieval-gate.ts, src/contracts/runtime-proof.ts, src/infrastructure/benchmark/runtime-proof.ts, src/runtime/retrieval-gate.ts, src/runtime/retrieve/slicing.ts, src/runtime/runtime-proof.ts, src/runtime/context-pack.ts, tests/unit/answer-ready-explain-pack.test.ts, tests/unit/benchmark-suite.test.ts	Runtime-proof schema, benchmark profile loading, strict retrieval overrides, retrieval slicing, and answer-ready gating are added for explain-runtime questions.
Compare/report runtime-proof plumbing src/infrastructure/compare.ts, src/infrastructure/context-pack-command.ts, src/runtime/stdio/tools.ts	Compare trace parsing, runtime-proof-aware readiness, prompt generation, and report merging now carry strict explain-runtime evidence through native-agent outputs.
Extraction and SPI graph pipeline src/pipeline/extract.ts, src/pipeline/extract/core.ts, src/pipeline/extract/cross-file.ts, src/pipeline/extract/frameworks/*, src/pipeline/extract/generic.ts, src/pipeline/extract/non-code.ts, src/pipeline/extract/python-rationale.ts, src/pipeline/spi/build.ts, src/pipeline/spi/cache.ts, src/pipeline/spi/framework-nextjs.ts, src/pipeline/spi/projector.ts, src/shared/source-discovery.ts	File-stem-based extraction IDs, cross-file resolution, SPI projection, and SPI cache/config discovery are updated across the extraction and graph-building pipeline.
Runtime context pack shaping src/infrastructure/context-pack-command.ts	Answer-ready explain packs and expandable previews are reworked around entrypoint-focused execution-spine context for runtime generation.
Runtime stdio tool overrides src/runtime/stdio/tools.ts	The stdio retrieve/context_pack tools now apply strict runtime-proof overrides and emit focused payloads when the matched benchmark profile requires them.
Runtime source discovery and tests src/shared/source-discovery.ts, tests/fixtures/go-semantic-workspace/cmd/chi/main.go, tests/unit/benchmark-suite-docs.test.ts, tests/unit/benchmark-suite-isolation-docs.test.ts, tests/unit/benchmark-suite.test.ts	Runtime source discovery, helper fixtures, and tests are updated to assert the new benchmark suite, runtime-proof, and isolation behaviors.

Sequence Diagram(s)

sequenceDiagram
  participant CompareTrace
  participant RuntimeProof
  participant ContextPack
  participant Report

  CompareTrace->>RuntimeProof: buildRuntimeProofAssessment(profile, candidates)
  RuntimeProof-->>CompareTrace: obligations, missing_obligations
  CompareTrace->>ContextPack: buildNativeAgentPrompt(strictRuntimeProof)
  CompareTrace->>Report: mergeCompareReportPackWithTraceFollowUps(...)
  Report-->>CompareTrace: answer_contract, execution_slice, readiness

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~90+ minutes

Possibly related PRs

• mohanagy/madar#517: Overlaps on scoped graphRoot benchmark wiring and the isolation launcher changes in docs/benchmarks/suite/* and src/infrastructure/benchmark/suite.ts.
• mohanagy/madar#519: Shares the runtime-proof contract and strict explain-runtime gating work across runtime-proof.json, compare/retrieval plumbing, and benchmark readiness checks.
• mohanagy/madar#518: Also changes src/runtime/context-pack.ts to alter partial explain answer-ready handling and missing-phase stop conditions.

Poem

I nibble receipts beneath the moon, 🐇
With graph roots scoped and profiles tuned.
I hop through proofs, both strict and bright,
And stash the clues in share-safe light.
Thump thump — the suite now knows the way!

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch next