Freshness checks, schema checks, and CI

There are two halves of map check. The Bash script handles mechanical evidence without a model or API key. The agent adds pointer, absorption, dependency, and coverage review. They have different verdicts and different limitations.

To run both through the agent:

/capstone:map check

To run only the mechanical half from your project root, using an installed/source copy of the same Capstone version:

bash /absolute/path/to/capstone/skills/core/scripts/map-check.sh docs/capstone

The full Capstone tree matters: the script reads the neighboring references/schema.txt and the plugin manifest. Copying only the script omits the schema/version information it expects.

Mechanical report#

These final verdict forms are literal script contracts:

MAP CHECK: current
MAP CHECK: stale (<N> findings)

<N> is replaced by the finding count. Exit code 0 means current, 1 means findings, and 2 means invalid usage such as an unknown flag or a supplied path that is not a directory. An existing docs directory without its index is a finding and reaches the stale verdict; a nonexistent directory exits as usage failure.

Informational commands are also literal supported shell options:

bash /absolute/path/to/capstone/skills/core/scripts/map-check.sh --help
bash /absolute/path/to/capstone/skills/core/scripts/map-check.sh --schema
bash /absolute/path/to/capstone/skills/core/scripts/map-check.sh --headings
bash /absolute/path/to/capstone/skills/core/scripts/map-check.sh --patterns

--schema prints the resolved file and record count; the inspected 6.4.1 source contains 23 records. --headings prints each topic's ordered headings. --patterns prints pattern names and regular expressions. These flags do not run the full report.

The schema uses first-match file patterns. Extra headings and columns are allowed, but required headings must appear in order. A required section may honestly say no applicable content was found. Entity subtables under Fields and types require Field, Type, and Required; an empty entity section is not excused the way an inapplicable general section can be.

On interfaces, a site must name one tracked file, not a directory or wildcard. Legacy :line suffixes are stripped. Prescriptive planned sites and non-Git projects skip tracked-site verification, but payload/model text checks still apply. known_as must be a YAML list, even when empty. The script does not resolve to/from repository names; Quarry handles that.

The model's report#

The agent first includes the script output, then adds:

Its final forms are:

MAP REVIEW: clean
MAP REVIEW: <N> findings

These are model protocol outputs rather than a shell process's independent semantic proof. The count covers parts 2–6. Disabled extraction passes report disabled, not missing; no frontend reports design coverage not applicable. Outside Git, the model side falls back to pointer drift.

Both halves are read-only. They do not regenerate files, fold fragments, record ledger entries, or fix findings. Run map for stale observed material, stack refresh for outdated research, or doctor for documentation-state repair.

Add the supplied GitHub Actions templates#

First generate and commit the reference. Then copy the source version's templates/capstone-map-check.yml to your repository's .github/workflows/ directory through your normal review process. The 6.4.1 template:

• Runs on pull requests with an Ubuntu runner.
• Checks out full Git history.
• Clones Capstone's v6.4.1 tag into the runner temporary directory.
• Runs the Bash script for docs/capstone and fails unless the last MAP CHECK: line is exactly current.

Adjust the docs-directory argument for custom paths or pass all workspace docs directories in the single script call. Keep the version pin deliberate: upgrading the checker can reveal documents written against older semantics even when their code did not change.

For the model half, use templates/capstone-map-review.yml and provide the ANTHROPIC_API_KEY repository secret. That template runs at 03:17 UTC daily and on manual dispatch. It installs Claude Code and the marketplace plugin, writes a headless global config, invokes /capstone:map check, and fails unless its last MAP REVIEW: line is clean. This template's plugin install is not pinned to 6.4.1; account for that when coordinating it with the pinned mechanical gate. The jobs deliberately consume different verdict lines.

For repositories connected to Quarry, run quarry init and quarry check alongside the freshness check on pull requests. Ensure the shared docs snapshot is sufficiently fresh; quarry check --sync requests a pull first. Capstone's template does not configure your Quarry registry or publish references for you.

Boundaries of the checks#

The secret scan recognizes six patterns: AWS access keys, GitHub tokens in the supported prefix shape, Slack tokens, Stripe secret keys, Google API keys, and private-key headers. It prints the pattern name, not the matched value. It skips ledger files/fragments, interviews, feature working files, reviews, configuration, ignore rules, and the UI preview. Tracked non-Markdown files in the docs area are scanned too; untracked non-Markdown scratch files inside Git are not. Therefore “schema: clean” is not a whole-repository secrets audit.

If the schema cannot be read, the script reports that headings/tables were not checked, applies its fallback checks, and can still print current. Missing semantic evidence, inaccurate coverage globs, and model mistakes are also outside a blanket guarantee. Read the report body as well as its last line.

Sources: actual checker, schema, model-half protocol, PR template, nightly template.