docs: redesign walkthrough pipeline map and clarify execution boundaries

[muratkeremozcan]

Summary

This PR redesigns docs/how-to/author-behavioral-contracts.md around a single, canonical numbered pipeline map that maps directly to the seven numbered walkthrough sections:

1. Unified Pipeline Map:

   • Replaced multiple competing conceptual diagrams with ONE canonical numbered pipeline map that spans Steps 1 through 7.
   • Visibly distinguishes executed CLI stages (compile, seal, preflight, score) from read-only inspection sections (Steps 2, 3, 7).

2. Explicit Execution Boundaries & Skipped Gaps:

   • Explicitly documented pipeline ownership: eval-quality CLI owns deterministic offline transformation/reduction, while the caller's evaluation harness owns dynamic environment and evaluator execution.
   • Defined the two execution gaps in the tutorial where prepared fixtures substitute for dynamic execution:
     • Preflight probing gap (before Step 5): The CLI command issues zero network requests and executes preflightFromObservations over prepared observations.json and probes.json. Explained that programmatic use with the TypeScript SDK can drive a live EnvironmentProbePort via runPreflight.
     • Evaluator & SUT execution gap (before Step 6): Explains that neither the defective Notes API nor an LLM evaluator is executed live; score replays the prepared sealed-run-record.json fixture.

3. Section Headings & Descriptions:

   • Renamed Step 5 from Preflight the environment to Reduce the preflight observations, clearly explaining that this step reduces prepared observations to a PreflightVerdict.
   • Renamed Step 6 to Score the evaluation record and clarified that it evaluates the prepared run record against the probe.
   • Updated the artifact map table to clearly indicate which artifacts are minted in this exercise vs replayed from committed inputs.
   • Updated the final summary flow under Key Takeaways to mirror the unified numbered pipeline.

Verification

• npm run docs:validate-links: 0 broken links.
• node scripts/check-docs.mjs: All files pass.
• node scripts/gates-cli.ts doc-invocations: 0 failures (54 run faithfully, 14 compared).
• node scripts/gates-cli.ts doc-counts: 42 numerals across 11 files, 0 disagreements.
• node scripts/gates-cli.ts doc-claims: 0 disagreements.
• vitest run tests/architecture/doc-gates.test.ts: 47/47 passing.
• node tools/build-docs.mjs: Clean build (17 pages generated).

[coderabbitai]

Warning

Review limit reached

Next included review available in 58 seconds.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: bmad-code-org/bmad-eval-quality/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 20931140-104c-4a0d-93d1-d59a36e4aed7

📥 Commits

Reviewing files that changed from the base of the PR and between fc32a3e and a15b56d.

📒 Files selected for processing (1)

• docs/how-to/author-behavioral-contracts.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}