sema AGENTS.md

Repository Agent Guide

This file is the repository-level operating context for coding agents. Detailed domain rules remain in the linked specifications; do not duplicate or invent them from prompt context.

Development Workflow

• Work on a focused feature branch and use a pull request. Do not merge until required CI is green.
• Keep unrelated user changes intact and surface unrelated defects separately.
• Use Henrik Westerberg <[email protected]> for locally authored commits. GitHub-created merge commits may use the account's noreply address; merge locally when every commit must use the organization address.
• Website and frontend experiments must remain on an isolated branch and staging service until Henrik explicitly approves production deployment.
• Paper typography or stylesheet work must remain separate from semantic paper updates unless visual redesign is the stated scope.
• Any change that touches paper/ must be built with scripts/compile_paper.sh, never bare pdflatex. The script regenerates the tables, the pattern-card appendix, the prose hash references and the stats macros, then runs bibtex and three pdflatex passes. Bare pdflatex leaves those stale: it once shipped 49 outdated hash stubs in the prose and a wrong pattern count, and a stale generated docs/information/audit.md from the same class of mistake failed CI on the 3.12 job, which is the only job that runs the vocabulary-workflow check.

Vocabulary Changes

Read these before editing patterns:

• docs/guides/authoring.md
• docs/guides/lifecycle.md
• docs/specification/schema.md
• docs/specification/validation.md

The database is authoritative. Copy exported JSON from data/vocabulary/ into data/staging/, edit staging, update data/design_critique.json, preview the manual, then apply. Never edit canonical vocabulary exports directly.

To apply, prefer:

python scripts/apply_vocabulary_change.py

It runs the four steps in the only order that works and stops at the first failure. It ignores any database selected by sema use and pins every subprocess to this checkout's authoritative data/taxonomy.db.