Milestone 8 of 8

Write and audit the engine card

Explain searchable terms, both position systems, phrase adjacency, proximity limits, result order, excerpts, missing cases, artifacts, replay evidence, and lexical limits.

The final artifact is an explanation constrained by the evidence, not a claim that lexical matching understands language. Write the engine card after the traces and replay can support it.

Goal

Write and audit report.md as a concise phrase-and-proximity engine card that explains the representation, matching rules, evidence, replay, and limits.

Inputs

Use the manifest, positional index, query analyses, phrase and proximity traces, ordered results, excerpts, summaries, figures and plot data, read-back checks, and replay agreement or mismatch record. The card must describe the actual versioned configuration and source identities used by the run.

Deliverables

The card must explain, in plain language:

  • which scanner records become searchable terms and which remain source-only;
  • the difference between contiguous indexed_position and complete-stream full_token_position;
  • phrase adjacency and offset intersection, including overlaps and repeats;
  • proximity direction, the intervening-term formula, boundaries, and same-term pair handling;
  • deterministic result order and one-excerpt-per-match construction;
  • invalid, missing, empty, and zero-term cases;
  • artifact names, read-back checks, plot-data evidence, and replay outcome; and
  • what the engine cannot claim from exact lexical positions.

Include a small worked trace that links a query, positions, match, and excerpt to the saved artifacts. Distinguish observations from interpretation and name any first mismatch honestly.

Checks

Audit every statement against a saved record or explicit rule. Reject wording that claims semantic understanding, relevance, probability, popularity, fairness, production performance, or ranking. Check that “exact phrase” means adjacent searchable terms, not raw-character equality; that excerpts retain source tokens without injected markup; and that replay claims agreement only when all required comparisons pass.

Check the card names missing and invalid cases, both proximity directions, zero and exact boundaries, repeated and same-term cases, and the distinction between candidate traces and returned matches. Confirm readers can locate each claim's supporting artifact.

Workspace

Keep the card at the project root as report.md. Do not replace the report with a presentation or a polished search-results mockup. Preserve all machine- readable artifacts and figures beside it.

Hints

HintStart with one trace
Write the worked example from a saved trace, then generalize the rule. This keeps the prose tied to an inspectable case.
HintName the coordinate
Whenever you say “position,” say whether it is a searchable-term position or a full-token position. The distinction is the project's central boundary.
HintLimits are part of the result
A careful card says what the evidence does not establish. Exact matches are useful records, not a measure of meaning or relevance.

Review

Give the card to a reader who has not opened the source code. Can they explain why one phrase survives and one proximity pair fails, find the supporting trace and excerpt, and tell whether replay agreed? Mark any sentence that outruns the artifacts.

How to check your work

Checks compare report.md with the evidence-limited reference card after completing your own audit. The supplied fixture explains the contract and cites artifacts; it does not conceal missing evidence behind confident language.