# `iftypeset` — Project Brief (downloadable)

## What This Is

`iftypeset` is a deterministic **Markdown → HTML → PDF** pipeline with:

- A **machine-readable rule registry** (Chicago/Bringhurst-backed pointers; paraphrased rules only)
- **Profiles** that map typographic intent → rendering tokens (`spec/profiles/*.yaml`)
- **QA gates** that fail builds when layout degrades (`spec/quality_gates.yaml`)

The wedge is not “perfect typography by AI”. The wedge is **CI for document quality**: measurable, reproducible, auditable.

## Non‑Negotiables

- No bulk OCR/transcription of Chicago/Bringhurst into the repo (copyright).
- Rules are paraphrases with pointer refs (e.g., `CMOS18 §X.Y pNN (scan pMM)`).
- If a rule cannot be automated safely, it must be tagged `manual_checklist=true` and emitted in `out/manual-checklist.md`.

## Where We Are (2026‑01‑03 snapshot)

Verified via `./scripts/ci.sh` (validate-spec + report + tests):

- CLI: `validate-spec`, `report`, `lint`, `render-html`, `render-pdf`, `qa`, `emit-css`
- Deterministic lint with safe rewrite mode (`lint --fix --fix-mode rewrite`)
- Deterministic HTML rendering; PDF rendering works when an engine is available
- QA (HTML-based v0) with incident details:
  - bare URL/DOI/email wrap risk
  - overfull token detection
  - table/code overflow (profile-aware thresholds)
- Forgejo CI workflow: `.forgejo/workflows/ci.yml`
- Session resilience tooling:
  - `./scripts/audit.sh`, `./scripts/resume.sh`, `./scripts/checkpoint.sh`
  - checkpoints tracked in `docs/CHECKPOINTS.md`

Rule registry snapshot (from `out/coverage-report.json`):

- Total rules: 524
- Enforced: 145 (lint + typeset + postrender)
- Manual: 379

The repo also emits a “trust contract” describing what is enforced vs manual:

- `out/trust-contract.md`
- `out/trust-contract.json`

## What’s Next (priority order)

1) **Make QA less “HTML heuristic” and more layout-aware**
   - Add at least one truly page-aware detector (widows/orphans or stranded headings) with measurable thresholds.

2) **Increase enforced coverage where it reduces real PDF pain**
   - citations normalization variants
   - link/DOI handling + wrap policy
   - table/code overflow strategies

3) **Forgejo integration**
   - run `iftypeset` as a PDF export/typeset worker
   - attach QA artifacts to exports

4) **Expand rule batches**
   - continue adding pointer-backed rules for remaining categories (figures, front/back matter, etc.)
   - promote high-confidence rules from `manual` → `lint/typeset/postrender` incrementally

## Quick Commands

From repo root:

- Resume sanity snapshot: `./scripts/resume.sh`
- CI sanity: `./scripts/ci.sh`
- Portable restore point: `./scripts/checkpoint.sh "note"`

## Canonical “single source of truth” docs

- `docs/09-project-status.md` (most current, short + factual)
- `docs/06-project-overview.md` (narrative overview)
- `docs/05-external-evaluation-prompt.md` (external review prompt)
- `docs/07-session-resilience.md` (how to avoid “lost work”)
- `docs/CHECKPOINTS.md` (restore points)