Clarify toRoutingHint behavior in README documentation

[lukefwalton]

Summary

Updated the README documentation to more clearly explain what the toRoutingHint function does and why it's important for maintaining privacy boundaries in the system.

Changes

• Revised the explanation of src/no-leak.ts to explicitly state that toRoutingHint drops the note's text
• Clarified that the privacy guarantee is enforced through the RoutingHint type's shape (which has no text field) rather than relying on runtime guards
• Improved readability of the documentation while maintaining the same core message about type-based privacy boundaries

Details

The change emphasizes that the security model depends on the type system itself: since RoutingHint has no field for note text, it's structurally impossible for private prose to leak to the model. This is a more precise explanation of why the small, auditable toRoutingHint function is critical to the system's privacy guarantees.

https://claude.ai/code/session_01113o5Rz53CzEJhqraQrRid

[surmado-code-review]

Automated Checks (advisory, non-blocking)

✅ All checks passed.

---

Standards Compliance

No standards violation is apparent from the PR description: this is a README-only clarification, and the behavior being documented (RoutingHint having no prose/text field and toRoutingHint dropping note text) is directly aligned with the repo’s Boundary Integrity standard.

One thing worth verifying in the README wording itself: make sure the clarification stays consistent with the full no-leak story from the standards, i.e. it reinforces RoutingHint’s shape-based boundary without implying other guards like assembleEvidence no longer matter. For a docs-only PR, that’s the main standards-sensitive detail.

Summary

This looks like a documentation-only PR that sharpens the explanation of src/no-leak.ts, especially why toRoutingHint matters and how the RoutingHint type enforces the privacy boundary structurally. No runtime behavior appears to change; the main value is making the repo’s core no-leak guarantee easier to understand from the README.
Reviewer: most of the risk is in whether the new README wording precisely matches the actual boundary guarantees — the rest is low-risk documentation cleanup.

What to pay attention to

• README claims about the privacy model: Since this repo’s main promise is the no-leak boundary, the reviewer should check that the new wording is precise and doesn’t overclaim or oversimplify. In particular, “type-shape boundary” is good, but it should still be accurate relative to the rest of the pipeline.
• Terminology alignment with standards/code: Make sure the docs use the same concepts the code and standards use (RoutingHint, private text/prose, no-leak boundary) so readers don’t come away with a subtly different mental model.

Things I noticed

If the README now explicitly says toRoutingHint drops note text and that RoutingHint has no text field, that will make the core privacy boundary easier to audit and understand.

No red flags are visible from the provided materials; this appears to be a low-risk doc clarification.

Good patterns

• Nice focus on the repo’s most important invariant: private prose staying out of model input.
• Good documentation direction: explaining why the boundary is safe, not just what function exists.

Suggested improvements

• Consider making sure the README wording still mentions that the boundary is part of a broader grounding/no-leak pipeline, so readers don’t interpret toRoutingHint as the only protection in the system.

Questions for the author

• Does the updated README wording still reference assembleEvidence anywhere nearby, or could a reader now infer that toRoutingHint alone is the complete enforcement point?

---

Surmado Code Review (v1.2-mt) is an automated review, designed to work alongside human judgment.

Want to change your STANDARDS.md or YML? Edit it directly, or tune it with our AI agent Scout.

Comment /rerun-review on this PR to refresh the review — costs 1 additional PR credit.