SPEC.md

SPEC.md — Engineering rules for G.U.I.D.E.

This file defines the non-negotiable process rules for changing this codebase. They exist to stop the kinds of drift and breakage we have actually hit while iterating. Read this before opening a change; the rules here are enforced by the sanity suite and the git pre-commit hook.

Sister docs: CLAUDE.md describes the architecture; the openspec/ workflow describes what to build. SPEC.md describes how every change must be made and verified.

---

1. Definition of Done (every change)

A change is not complete until all of the following hold:

1. Sanity tests pass — python -m pytest tests/test_sanity.py -q is green. No code may be committed while sanity tests fail (enforced by the pre-commit hook — see §4).
2. The “How To Guide” tab is in sync — see §2.
3. Docs reflect the change — if you changed architecture, tabs, endpoints, env vars, or invariants, update CLAUDE.md (and README.md if user-facing).
4. No secrets added — API keys/tokens live only in the git-ignored .env. Never paste them into source, tests, or commit messages.

2. The “How To Guide” tab MUST be kept in sync

The first tab in ui/app.py (📖 How To Guide) is the user's onboarding doc. Any UI change that affects what the user sees or does must be reflected there, specifically:

• Adding, removing, or renaming a tab → update the “What Each Tab Does” table (and the Step-by-Step Flow table if it changes the main flow).
• Adding or changing a user-facing feature (e.g. PDF export, the redaction reveal panel, the privacy audit) → describe it in the relevant tab row and, if it touches privacy, in the “Your Privacy” section.
• Changing the privacy behaviour → keep the “Your Privacy” section honest.

This rule is partially automated: test_how_to_guide_lists_every_tab fails if any user-facing tab is not mentioned in the How To Guide. The judgement calls (feature descriptions, privacy wording) are on the author — keep them current.

3. Sanity test suite

Location: tests/test_sanity.py. It is fast (no ML checkpoints, no spaCy model, no Anthropic API, no network) and covers:

Check	Guards against
Gradio app builds (build_app())	event/component wiring, output-count, scope bugs
API models + routes import & validate	request/response schema breakage
RedactionResult.spans contract	the redaction-reveal data contract
Redaction-reveal / audit-log render helpers	the two privacy features silently breaking
PDF export produces a real %PDF- file	the export feature breaking
Friendly LLM-error mapping	overloaded/rate-limit/timeout → user-friendly message
How To Guide lists every tab	the guide drifting out of sync (see §2)

When you add a feature, add a sanity check for it here if it is cheap to verify without heavy dependencies. Keep the whole suite under ~15 seconds.

The deeper unit tests under tests/<module>/ (classifier, ner, agent, privacy, etc.) are not part of the commit gate — run them with pytest tests/ when you touch those layers.

4. Enforcement — git pre-commit hook

A pre-commit hook runs the sanity suite and blocks the commit if it fails.

Install it once after cloning (idempotent):

bash scripts/install-hooks.sh

This copies scripts/hooks/pre-commit into .git/hooks/ and marks it executable. The hook runs tests/test_sanity.py in the project .venv (falling back to python3). To bypass in a genuine emergency only: git commit --no-verify — but the change is then not Done per §1.

5. Checklist to paste into a PR / change description

- [ ] Sanity tests pass: pytest tests/test_sanity.py -q
- [ ] How To Guide tab updated (tabs / features / privacy wording)
- [ ] CLAUDE.md / README.md updated if architecture or behaviour changed
- [ ] No secrets added to source or commits
- [ ] Added a sanity check for any new user-facing feature (if cheap)