dannystocker/iftypeset
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iftypeset/docs/08-handoff.md
codex f8808cecd1
Some checks are pending
ci / ci (push) Waiting to run
Details
docs: add zero-context explainer
2026-01-08 20:49:59 +00:00

3.5 KiB
Raw Export PDF Permalink Blame History

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:

./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:

./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
  • Zero-context explainer: docs/20-iftypeset-zero-context-explainer.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