# Handoff (context checkpoint) — `iftypeset`

This file exists for one purpose: prevent “chat drift” when a session resets.

If the conversation disappears, this doc + `./scripts/audit.sh` is enough to resume work.

## What this project is

`iftypeset` (pubstyle) is a thin, deterministic **Markdown → HTML → PDF** pipeline with:

- A **machine-readable rule registry** (`spec/rules/**.ndjson`) with **paraphrased** rules + **pointer refs** (Chicago/Bringhurst), never book text.
- **Profiles** (`spec/profiles/*.yaml`) that map typographic intent → render tokens/CSS.
- **QA gates** (`spec/quality_gates.yaml`) that fail builds when layout degrades.

Core principle: quality must be **measurable and enforceable**, not “looks fine on my machine”.

## What is working (today)

- CLI (end-to-end): `validate-spec`, `report`, `lint`, `render-html`, `render-pdf`, `qa`, `emit-css`.
- Rendering: HTML deterministic; PDF works when a PDF engine is available (Playwright is the default).
- QA (v0): HTML-based heuristics + gate evaluation; emits `layout-report.json` with incident details.
- Rule registry: seeded and schema-validated; coverage report is generated in CI.
- CI: `./scripts/ci.sh` runs spec validation + report + unit tests.
- Session resilience:
  - `./scripts/audit.sh` prints git + coverage snapshot + checkpoint info.
  - `./scripts/checkpoint.sh "note"` creates a restore tarball and records it in `docs/CHECKPOINTS.md`.

## How to resume in 30 seconds

From repo root:

```bash
./scripts/audit.sh
./scripts/ci.sh
```

If CI passes, you are back.

## Latest checkpoint (restore point)

Run `./scripts/audit.sh` to see the latest checkpoint path + sha256.

If you need to create a new restore point:

```bash
./scripts/checkpoint.sh "short note about what changed"
```

## Where to look first

- Status and counts: `STATUS.md`
- Project status (narrative): `docs/09-project-status.md`
- Architecture: `app/ARCHITECTURE.md`
- CLI contract: `app/CLI_SPEC.md`
- External evaluation prompt: `docs/05-external-evaluation-prompt.md`
- Renderer strategy: `docs/04-renderer-strategy.md`
- Session resilience: `docs/07-session-resilience.md`
- Rule schema + contracts: `spec/schema/rule.schema.json`, `spec/manifest.yaml`

## Non-negotiables (don’t drift)

- Do **not** OCR/transcribe Chicago/Bringhurst into the repo.
- Rules are **paraphrases** + **pointer refs** only.
- OCR is allowed only **ephemerally** to locate pointers (stdout/temp deleted).
- If a rule cannot be automated, mark it `manual_checklist=true` and ensure it lands in checklist output.

## What remains (next high-leverage work)

1) **Deepen post-render QA**
   - Current QA is HTML-based v0.
   - Next step is PDF-aware inspection for widows/orphans, stranded headings, and clipping when a renderer is pinned.

2) **Increase enforced coverage where it buys down real pain**
   - Citations and i18n where deterministic checks are feasible.
   - Links/DOIs wrapping policies and table/code overflow strategies across profiles.

3) **Forgejo integration**
   - Apply profile CSS to Forgejo’s PDF exporter and emit QA reports as export artifacts.
   - See `forgejo/README.md`.

4) **More rule batches**
   - Build out figures/links/code/frontmatter/backmatter/i18n breadth, then tighten enforcement coverage where feasible.

## “Don’t lose work” reminder

Chat logs are not durable. The repo is.

- When you finish a chunk: `./scripts/checkpoint.sh "note"`
- When you resume: `./scripts/audit.sh` + `./scripts/ci.sh`