check-self-reference.yml

Diff-scoped check that flags self-referential prose. It fails by default, since agents ignore warnings (Ezra, 2026-11-02). The notes write about their content, not their own structure (Ezra, 2026-11-03): “The negative gradient decreases the cost the most”, not “This exercise shows that the negative gradient is the best answer”. The rule text is in psw, “Avoid forward references”.

The check flags a sentence that starts with “This” or “These”, then a structural noun (exercise, solution, section, chapter, lecture, page, handout), optionally “and the ones that follow it”, then a verb that reports what the structure does: shows, establishes, explains, says, derives, proves, covers, introduces, demonstrates, illustrates, describes, computes, handles or “is about”.

The check also flags a sentence that starts with “The next”, “The previous”, “The preceding” or “The following” and then exercise, solution, section, chapter, lecture or example (plural allowed), such as “The next exercises establish the properties”. Name the items by cross-reference instead: “Exercises ?@exr-a through ?@exr-b establish the properties” (psw, “Avoid forward references”).

The check does not count:

a line inside a code fence, an HTML comment or the YAML front matter;
a sentence about a figure, table or example placed beside it, such as “Table 2 shows the estimates”;
a line carrying .

Where an overview of a group of items goes (in its own paragraph before the first item) cannot be detected, so this check covers only the self-reference half of the rule.

Scope

A finding is reported only when the line was added in the pull request, so existing sentences are not swept. With no base-ref, or when the diff cannot be computed, the check skips with a warning instead of scanning the whole tree. Set whole-tree: true to scan every tracked page in full on purpose, which measures how many sentences a corpus carries that break the rule.

Inputs

Input	Type	Default	Description
`globs`	string	`'*.qmd'`	Space-separated git pathspecs of tracked files to check (recursive by default).
`paths-ignore`	string	`''`	Comma- or newline-separated glob patterns (relative paths) to skip. Supports ``, `?` and recursive `*`.
`fail`	boolean	`true`	Fail the workflow when an added sentence is self-referential. Set `false` for warning annotations only.
`whole-tree`	boolean	`false`	Scan every tracked page in full instead of only a PR’s added lines.
`python-version`	string	`'3.x'`	Python version to set up.
`runs-on`	string	empty (`CI_RUNNER` variable, else `ubuntu-latest`)	Runner label for the job. Use a self-hosted label only for a private repository; never for a public one, whose pull requests can run arbitrary code on it (#1167).

Permissions

Only contents: read (the default), so no permissions: block is needed.

Example

# Copy to .github/workflows/check-self-reference.yml in your repo.
# Diff-scoped check: flags self-referential prose when a PR adds it: a sentence that starts with "This" or "These" and a structural noun (exercise, solution, section, chapter, lecture, page, handout) and a verb such as shows, establishes, explains, covers or "is about".
# Fails by default.
# Only contents:read is needed (the default), so no permissions block is required.
name: Check self-referential prose

on:
  push:
    branches:
      - main
  pull_request:
  workflow_dispatch:

jobs:
  check:
    uses: Morrison-Lab/gha/.github/workflows/check-self-reference.yml@v3
    # with:
    #   globs: '*.qmd'                         # pathspecs to check (recursive)
    #   paths-ignore: 'chapters/outtakes/**'   # skip known-noisy paths
    #   fail: false                            # warn instead of block (defaults to true)
    #   whole-tree: true                       # scan every page, not just a PR's additions

See examples/check-self-reference.yml for the full caller stub.