docs: position Madar for review and security workflows

[mohanagy]

Summary

• position Madar as a context/evidence layer for AI review and security workflows instead of another reviewer
• document a concrete review/security-agent evaluation flow around review-compare, pr_impact, and share-safe receipts
• ground the new positioning in claims-and-evidence and lock it with doc tests

Test Plan

• npm run test:run -- tests/unit/why-madar-doc.test.ts
• npm run typecheck
• npm run build
• CI=1 npm run test:run

Closes #437

Summary by CodeRabbit

Release Notes

• Documentation

  • Clarified Madar's role as a context/evidence layer for review and security workflows (not a reviewer or scanner)
  • Added guidance on which artifacts to use for different review/security workflows
  • Documented new workflow for integrating Madar with review/security agents

• Tests

  • Enhanced documentation accuracy verification for positioning claims

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 2863f183-b605-44b2-847e-d9f0eeec27d0

📥 Commits

Reviewing files that changed from the base of the PR and between b799ff4 and 2d4f244.

📒 Files selected for processing (4)

• README.md
• docs/claims-and-evidence.md
• docs/proof-workflows.md
• tests/unit/why-madar-doc.test.ts

---

📝 Walkthrough

Walkthrough

This PR positions Madar as a local context and evidence layer for review and security tools—not as a reviewer or vulnerability scanner itself. It documents evaluation workflows, adds supporting claims with measured boundaries, and enforces positioning language honesty through new tests.

Changes

Review/security tool positioning

Layer / File(s)	Summary
README review/security workflows section README.md	README adds a "Review and security workflows" section clarifying Madar's role, listing recommended artifacts for supplying context/evidence, and referencing bounded claims documentation.
Claims and evidence updates for context/evidence layer docs/claims-and-evidence.md	New in-progress claim (22) describes Madar as a context/evidence layer for review/security tools via workflow guidance; new not-yet-measured claim (29) documents that no broad comparative evaluation receipts exist for default tool improvement.
Review/security-agent evaluation workflow documentation docs/proof-workflows.md	Adds workflow section (3.5) detailing steps to evaluate Madar's bounded diff evidence alongside external review/security agents, including artifact handling and explicit scope limitations.
Documentation honesty tests for positioning tests/unit/why-madar-doc.test.ts	Vitest assertions enforce that README frames Madar as context/evidence layer (not reviewer/scanner), proof-workflows maps to review-compare and report.share-safe.json without overstating proof capabilities, and claims-and-evidence ties positioning to workflow guidance rather than unmeasured superiority.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• mohanagy/madar#334: Updates the same "claims vs. evidence / docs honesty" material in docs/claims-and-evidence.md and tests/unit/why-madar-doc.test.ts to ensure README and security workflow wording remains bounded by evidence.
• mohanagy/madar#446: Introduces the madar handoff share-safe command and artifact behavior that aligns with this PR's documentation of madar handoff as a recommended artifact for review/security workflows.

Poem

🐰 A rabbit hops through docs, laying out the truth so clear:
Madar's not a reviewer—just evidence held here.
No scanner, no oracle, just context bound and tight,
Help your favorite agents see the diff in clearer light. 🔍✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: positioning Madar for review and security workflows, which is the core objective of this PR.
Description check	✅ Passed	The description covers key changes, includes a Test Plan with checkboxes (though uses inline checkmarks instead of template format), references the linked issue, and provides sufficient detail about the PR's intent.
Linked Issues check	✅ Passed	The PR fully addresses issue #437 acceptance criteria: it positions Madar as a context/evidence layer in README, documents a review/security-agent evaluation workflow in proof-workflows.md, and grounds claims in claims-and-evidence.md with supporting tests.
Out of Scope Changes check	✅ Passed	All changes are tightly scoped to repositioning Madar for review/security workflows: README clarifications, new workflow documentation, expanded claims documentation, and supporting tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 issue-437-review-security

---

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