docs: state the premise and what a refusal means

[lukefwalton]

What & why

A clarity change to README.md and paper.md. No code, no argument change.

A reader who meets the no-leak boundary first tends to read "who decides what belongs in the archive?" as an open question the engine has not answered. It is answered by premise, and the README and paper now say so where the first argument lands:

• The premise (README §1; paper Summary, one sentence). The archive has an owner, the author. What enters, how much of each piece may travel, and when the system declines are the author's decisions, made before any question arrives. The engine's job is to keep those decisions in force at the one place a model would dissolve them: where the model's capacity to produce a plausible answer gets mistaken for the authority to give it. The model's competence is deliberately greater than its permission.
• What a refusal means (README §4; paper Software design, one paragraph). not-found says the archive authorized no answer, not that the question is unanswerable, that no evidence exists, or that the author has no view. related-material says evidence exists and may only be pointed to. A refusal is a disciplined non-assertion, not a claim to know the limits of one's own knowledge.
• Limits (README "What this shows"). Who decides is not an open question here; what the code settles is whether those decisions survive contact with a model that could infer past them. And the guarantee is about what reaches the model and the wire, not provider custody (private text already leaves for the embedding provider at ingest), with pointers to SECURITY.md and docs/CONTRACT.md.

Paper housekeeping to stay under the JOSS cap: the brute-force-cosine clause is folded into the consumer sentence, a phrase duplicated between Summary and Research impact is dropped, and the inventory sentence names the two index formats and the evaluation harness. Body is 1,749 words; all 22 citations resolve; 0 contractions, 0 em-dashes.

Checklist

• npm test passes without an API key (the offline CI gate) — no hidden
  dependency on live calls
• npm run typecheck passes
• No change that makes the eval pass by special-casing a question (fixes go
  into the corpus, scoring, or prompt)
• A boundary stays structural (a type, not a checker someone must remember),
  if this touches the no-leak path (not touched)
• Touched the prompt / retrieval / validation / repair? Ran the relevant
  npm run eval subset (not touched)
• Read against .github/STANDARDS.md — the rubric a PR is judged by

🤖 Generated with Claude Code

https://claude.ai/code/session_01F2ti456guy1bXVmjA3fBTV

---

Generated by Claude Code

[surmado-code-review]

Automated Checks (advisory, non-blocking)

✅ All checks passed.

---

Standards Compliance

No served-path, retrieval, validation, repair, or eval code changes are visible here; based on the PR description this is a docs-only update to README.md and paper.md, so the repo’s non-negotiable boundary rules are not directly changed.

[UNVERIFIED] Since the actual diff content isn’t included in this review context, the main standards check I’d do before merge is wording consistency in README.md and paper.md against the existing contract docs:

• refusal semantics stay aligned with the standard language:
  • not-found = the archive authorized no answer
  • related-material = evidence exists but may only be pointed to
• custody language does not overstate confidentiality from providers; the guarantee is about the served boundary, not provider secrecy (SECURITY.md, docs/CONTRACT.md §10)
• the docs keep describing author decisions as pre-query policy/exposure choices, not something inferred or decided by the model at answer time

From the PR description, the edits sound aligned with those standards rather than in tension with them.

Summary

This looks like a documentation clarification pass over README.md and paper.md to make the archive-owner premise, refusal semantics, and custody limits explicit earlier in the narrative. It doesn’t appear to change behavior, but it does touch the two places readers will use to understand the project’s guarantees, so the main review task is checking factual consistency with docs/CONTRACT.md and SECURITY.md.

Reviewer: most of the risk is prose drift from the contract/security docs — there’s no implementation risk visible here.

What to pay attention to

• README.md refusal wording: make sure the new explanation does not blur “unauthorized to answer” into “unknowable” or “no evidence exists.”
• paper.md custody framing: confirm it stays as narrow as the standards require — private text may leave for embedding/drafting providers, and the guarantee is about what reaches the model on the served path and the wire.
• Cross-doc term consistency: these concepts should use the repo’s exact terms (not-found, related-material, exposure/policy, author-set decisions) so the docs don’t drift from the design of record.

Things I noticed

• No clear red or yellow flags are visible from the provided material; this appears to be a documentation-only PR.
• [UNVERIFIED] One thing to sanity-check before merge: that README.md still states the concrete observable behavior of not-found somewhere, not just the philosophy. The standards are specific that not-found means empty answer + zero citations.

Good patterns

• Good to see the custody limit made explicit instead of strengthening the privacy claim; that matches the repo standard to name custody accurately, not overstate it.
• Clarifying refusals as disciplined non-assertions is consistent with the project’s boundary discipline and should reduce a common reader misunderstanding.

Suggested improvements

• If not already present, add a direct cross-reference from both README.md and paper.md to docs/CONTRACT.md for refusal semantics and to SECURITY.md / contract §10 for custody. That gives readers one authoritative place to reconcile the prose.

Questions for the author

• Does the revised README.md still mention the concrete output shape of a not-found response somewhere, or was this change intentionally limited to its meaning? I’d keep the “empty answer + zero citations” behavior explicit if it moved.

---

Surmado Code Review (v1.5-mt, review #1 on 38c035e) 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 re-review the current code with your latest STANDARDS.md and config — costs 1 additional PR credit (limit 3/hour per PR).

[lukefwalton]

Answering the reviewer's question: yes, the concrete shape is still stated. The modes table in README.md §4 keeps the row not-found | none, empty answer, and the paragraph below it still says the validator rejects a not-found with prose. The new "What a refusal means" paragraph sits after that table and only adds what the empty answer asserts. The paper's custody sentence is in README.md only (the paper names docs/CONTRACT.md as the design of record and leaves custody to SECURITY.md); the README paragraph links both.

---

Generated by Claude Code