check-latex

Files (3)

• SKILL.md
• check-latex.sh
• scope.py

SKILL.md (first lines)

> **Canonical copy**: `mathcity.check-latex` in this mathcity pack.
> **STATUS: PRELIMINARY (DRY-RUN ONLY).** Read-only. Writes ONLY under
> `<city-root>/tmp-for-review/<bead>/`. No `Edit`/`Write`/`git commit`/`git push`/`bd update`.
> This skill NEVER approves a diff — it produces evidence for the human adjudicator to approve or reject.

# check-latex

The runnable screening artifact behind the **LaTeX HARD GATE**: any edit to
`notes.tex` or any main-branch `.tex` file in the notes-tier of the
`differential-valuations`, `hecke`, `homog`, or `jacobi` rigs requires the human adjudicator's
explicit approval of the **specific diff** before it may be pushed or merged.

This skill produces the evidence the human adjudicator needs to make that call. It does not
adjudicate, does not merge, and does not push. Its output is the artifact the
`latex-gate` formula (F1b) requires and the `he-86wu` gate-release consumes.

Policy lineage: `he-jwmy` (LaTeX-gate-policy — canonical charter), `he-hsoc`
(umbrella spec), `he-86wu` (gate-release criterion, first instance
`polecat/he-d4l`), `he-cnat` (preliminary-skill-first).

## When to use

Use whenever a diff touches a **covered** `.tex` file (see Scope) and you need
the gate evidence before adjudication happens a push/merge. Also used as the
callee of the `latex-gate` formula and to release the `he-86wu` block.

## Scope (covered files) — per he-jwmy

A `.tex` file is **covered** when any of:

- it is named `notes.tex` at any depth, OR
- it lives under a `latex/notes/` tree, OR
- it is `\input`'d or `\include`'d by such a file at depth ≤ 2 (the depth-2 cap
  makes the rule mechanically checkable with
  `grep -E '\\(input|include)\{' notes-tier.tex`).

**Out of scope** (per he-jwmy): a `.tex` file satisfying ALL of (a) under
`scratch/`, `tests/`, `fixtures/`, or a path containing `tmp/scratch/fixture/test`,
AND (b) no `\label{}` reachable from any notes-tier `\ref{}`/`\eqref{}`, AND
(c) not in the depth-2 `\input`/`\include` closure. Autogenerated `.tex` is out
of scope only if the generator is documented AND the file carries a
`% AUTOGENERATED` marker.

## Workflow

1. **Compile** the root document with the first available TeX tool
   (latexmk → pdflatex → xelatex → lualatex → tectonic); if none is present,
   report `toolchain-unavailable` and NEVER fake a compile result.
2. **Select the requested scope**, when `--section`/`--scope` is provided, by
   numbered heading (`2.1` or `2.1.1`), `label:<label>`, or exact heading title.
   A root document is expanded through `\input`/`\include` so numbering follows
   the compiled document; the target file supplies the source range to scan.
3. **Semantic-diff** the change: enumerate sections, theorem-class environments,
   equations, labels, citations, and unfinished-tag deltas touched.
4. **Emit** the evidence block (`files touched · compile status · semantic
   summary · exact diff pointer`) as `check-latex-report.{json,md}` under
   `<city-root>/tmp-for-review/<bead>/` for the human adjudicator to approve or reject.

## How (invocation)

```bash
# From inside the repo containing the .tex (git diff needs a repo):
skills/check-latex/check-latex.sh <tex-file> \
    [--root <root.tex>]         # document to compile; defaults to <tex-file>
    [--section <selector>]      # numbered heading, label:<label>, or exact title
    [--scope <selector>]        # alias for --section
    [--base <git-ref>]          # merge-base or branch point; default: working-tree vs HEAD
    [--out <dir>]               # default: <city-root>/tmp-for-review/<bead>/
    [--bead <id>]               # bead this screening is for; default: unbeaded
```

For an included chapter, compile the real root while scanning only one
subsection:

```bash
skills/check-latex/check-latex.sh latex/aws-notes-v1/ch1-groups.tex \
    --root latex/aws-notes-v1/main.tex --section 2.1 --bead aws-notes-v1
```

Use `--section 2.1.1` for a subsection, `--section label:sec:hyperbolic` for
a label, or `--section 'Hyperbolic $n$-space'` for an exact heading title.

The helper `check-latex.sh` is the mechanical evidence engine. It:

- picks the first available TeX build tool and records `compile.status` as one of
  `pass`, `pass-with-undefined-refs`, `fail`, or `toolchain-unavailable` — the
  last is the graceful-degradation path (compile skipped, explicitly NOT faked).
  It compiles `--root` and records that path in the report; this lets an included
  fragment be checked in its actual document context;
- acquires the diff via `git diff [<base>] -- <file>` (or working-tree vs HEAD),
  falling back to whole-file content when the target is not in a git repo;
- handles untracked targets as a `/dev/null` → file diff so newly created chapters
  and sections can be scoped before they are staged;
- when `--section`/`--scope` is present, resolves the heading through the root's
  input/include closure, filters the target's diff to that heading block, and
  records the selector, heading, labels, and source line range;
- scans the added/removed lines for `\section`/`\subsection`, theorem-class
  environments (`theorem`, `proposition`, `lemma`, `corollary`, `definition`,
  `remark`, `example`, `conjecture`, `question`, `claim`), display-math
  environments, `\label{}`, `\cite{}`, and unfinished tags
  (`\reviewer`/`\david`/`\claude`/`\note`/`\todo`);
- writes `check-latex-report.json` (machine-readable) and
  `check-latex-report.md` (the human evidence block) plus `compile.log` and
  `tex.diff`; scoped runs also write `scope.json`, `scope-source.txt`, and
  `scope-diff.txt` under the same output directory.

## Evidence block (what the human adjudicator gets)

The `.md` report is the decision surface. It contains exactly:

1. **Compile status** — `pass` / `pass-with-undefined-refs` / `fail` /
   `toolchain-unavailable`, with the tool used and a log pointer.
2. **Files touched** — the covered `.tex` files changed by this diff.
3. **Semantic diff summary** — sections, theorem-class environments, equation /
   label / citation / unfinished-tag counts touched.
4. **Requested scope** — selector, matched heading, labels, and source line
   range when `--section`/`--scope` was used.
5. **Diff pointer** — the exact `tex.diff` path the human adjudicator can open, plus the diff
   basis (base ref or working-tree).

From tdupu/agent-skills-public, GPL-3.0.

More from tdupu/agent-skills-public