> For the complete documentation index, see [llms.txt](https://docs.thecolliery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thecolliery.org/tools/coalmine.md).

# CoalMine

## 🐤 CoalMine

> *A mine's canary dies first so the miners live — these nine die first so your codebase lives.*

**9 Quality-Safeguard Canaries for AI Coding Agents** — Detect code rot, weak rules, hallucinations, supply-chain vulnerabilities, brittle architectures, and API contract drift before they pollute your codebase.

![version](https://img.shields.io/github/v/tag/TheColliery/CoalMine?label=version\&color=blue) ![license](https://img.shields.io/badge/license-Apache_2.0-blue) ![status](https://img.shields.io/badge/status-live-brightgreen) ![SKILL.md](https://img.shields.io/badge/SKILL.md-open_standard_%C2%B7_major_agents-success) ![skills](https://img.shields.io/badge/skills-9-success) ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/TheColliery/CoalMine?utm_source=oss\&utm_medium=github\&utm_campaign=TheColliery%2FCoalMine\&labelColor=171717\&color=FF570A\&link=https%3A%2F%2Fcoderabbit.ai\&label=CodeRabbit+Reviews) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/16501/badge)](https://www.bestpractices.dev/projects/16501)

![Claude Code](https://img.shields.io/badge/Claude_Code-validated-brightgreen) ![Antigravity](https://img.shields.io/badge/Antigravity-validated_canaries_%C2%B7_primed_auto--cadence-brightgreen) ![Cursor](https://img.shields.io/badge/Cursor-works_with-blue) ![Codex](https://img.shields.io/badge/Codex-works_with-blue) ![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-works_with-blue) ![Cline](https://img.shields.io/badge/Cline-works_with-blue) ![Copilot](https://img.shields.io/badge/Copilot-works_with-blue) ![claude.ai](https://img.shields.io/badge/claude.ai-ZIP_upload_confirmed_2026--10--09-blue)

[Design Principles](https://github.com/TheColliery/.github/blob/main/DESIGN-PRINCIPLES.md) · [Benchmark](https://github.com/TheColliery/.github/tree/main/benchmarks/CoalMine) · [Contributing](https://github.com/TheColliery/CoalMine/tree/main/CONTRIBUTING.md) · [Changelog](/tools/changelog.md) · [Security](https://github.com/TheColliery/CoalMine/tree/main/SECURITY.md) · [Privacy](https://github.com/TheColliery/CoalMine/tree/main/PRIVACY.md) · [Releases](https://github.com/TheColliery/CoalMine/releases)

**Docs:** [docs.thecolliery.org/tools](https://docs.thecolliery.org/tools)

**Part of** [**TheColliery**](https://github.com/TheColliery) — siblings: [**CoalTipple**](https://github.com/TheColliery/CoalTipple) (model/effort routing) · [**CoalBoard**](https://github.com/TheColliery/CoalBoard) (consensus & debate board) · [**CoalHearth**](https://github.com/TheColliery/CoalHearth) (session warm-resume) · [**CoalFace**](https://github.com/TheColliery/CoalFace) (fan-out discipline) · [**CoalWash**](https://github.com/TheColliery/CoalWash) (memory defrag) · [**CoalLedger**](https://github.com/TheColliery/CoalLedger) (docs health).

***

### 🐤 The 9 Canaries

| Skill Name               | Catches                                                                                                        | Run Mode                                                                                                                                                                                                   |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`rot-canary`**         | Dead code, bugs, resource leaks, race conditions, silent failures, stale docs                                  | **Auto + Manual** (runs on session end / manual trigger)                                                                                                                                                   |
| **`gold-standard`**      | Audits project completeness against world-class exemplars                                                      | **One-time** (triggered once, governs the session)                                                                                                                                                         |
| **`source-grounding`**   | Prevents AI hallucinations by forcing cross-source verification                                                | **Standing rule** (always on only where your own `CLAUDE.md` or `AGENTS.md` carries it; CoalMine writes no such file) · offered at session start on version-sensitive work · `/source-grounding` on demand |
| **`supply-chain-audit`** | Audits dependency vulnerabilities, licenses, phone-home code, and build/CI security                            | **On-demand** (manually run when relevant)                                                                                                                                                                 |
| **`resilience-audit`**   | Audits failure path handling (FMEA), rollbacks, retry limits, and idempotency                                  | **On-demand** (manually run when relevant)                                                                                                                                                                 |
| **`telemetry-canary`**   | Audits observability, log structures, metrics, and telemetry quality, and flags sensitive data written to logs | **On-demand** (manually run when relevant)                                                                                                                                                                 |
| **`testability-canary`** | Audits testing ease, code coupling, mockability, and Dependency Injection (DI)                                 | **On-demand** (manually run when relevant)                                                                                                                                                                 |
| **`scale-canary`**       | Audits performance scaling issues, $O(N^2)$ loops, and duplicate (N+1) database queries                        | **On-demand** (manually run when relevant)                                                                                                                                                                 |
| **`drift-canary`**       | Prevents contract and schema drift (API/database contract inconsistencies)                                     | **On-demand** (manually run when relevant)                                                                                                                                                                 |

*Run Mode Details:*

* 📌 **Standing rule:** `source-grounding` is a rule for your agent, not a background process. It is always on where your own `CLAUDE.md` or `AGENTS.md` says so (CoalMine does not write that line for you); otherwise the session-start conductor offers it when you work on version-sensitive facts, and `/source-grounding` runs it on demand.
* 🔄 **Auto + Manual:** Scans affected files at session end via lifecycle hooks (auto-wired in Claude Code; manual snippets in [`platform-configs/hooks/`](https://github.com/TheColliery/CoalMine/tree/main/platform-configs/hooks/README.md) for other agents). Manual trigger via `/rot-canary`.
* ⚡ **One-time:** Governs the session by scanning and filling project-local rules.
* 🎯 **On-demand:** Manually run for specific tasks to conserve tokens.

*Canaries follow **grounding in evidence, zero grade inflation, and report before fixing**. Fixes apply through a safe loop: checkpoint, baseline build and tests, apply the fix, build and tests again, and auto-revert only on a NEW failure.*

*Em-dash typography (`unspaced`/`spaced`/`off`, house style) is not one of the 9 — that rule belongs to* [*CoalLedger*](https://github.com/TheColliery/CoalLedger)*'s `doc-quality` canary (`emDash` config key, factory default `off`), never duplicated here.*

***

### 🔌 Universal Agent Support

`SKILL.md` is an **open standard** compatible with all major AI coding agents:

| AI Agent                                                                            | Target Skills Folder                              | Installation Shortcut                  | Choice Tool Support                       |
| ----------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------- | ----------------------------------------- |
| **Claude Code**                                                                     | plugin cache (recommended) or `~/.claude/skills/` | `/plugin install coalmine@coalmine`    | ✅ **Native:** `AskUserQuestion`           |
| **Antigravity**                                                                     | `.agents/skills/`                                 | `node scripts/install.mjs antigravity` | ✅ **Native:** built-in question prompt    |
| **Cursor**                                                                          | `.cursor/skills/`                                 | `node scripts/install.mjs cursor`      | ✅ **Native:** built-in ask-question tool  |
| **Devin Desktop (ex-Windsurf)**                                                     | `.windsurf/skills/`                               | `node scripts/install.mjs windsurf`    | ✅ **Native:** `suggested_responses`       |
| **GitHub Copilot**                                                                  | `.github/skills/`                                 | `node scripts/install.mjs copilot`     | ✅ **Native:** `askQuestions`              |
| **Cline**                                                                           | `.claude/skills/`                                 | `node scripts/install.mjs cline`       | ✅ **Native:** `ask_question`              |
| **Gemini CLI (business-tier; individual tiers ended 2026-06-18 → Antigravity CLI)** | `.gemini/skills/`                                 | `node scripts/install.mjs gemini`      | ✅ **Native:** `ask_user`                  |
| **Goose**                                                                           | `.agents/skills/`                                 | `node scripts/install.mjs goose`       | ⚠️ **Text Fallback:** no question tool    |
| **Amp**                                                                             | `.agents/skills/`                                 | `node scripts/install.mjs amp`         | ⚠️ **Text Fallback:** tool not documented |
| **Junie**                                                                           | `.junie/skills/`                                  | `node scripts/install.mjs junie`       | ⚠️ **Text Fallback:** tool not documented |
| **Codex**                                                                           | `.agents/skills/`                                 | `node scripts/install.mjs codex`       | ✅ **Native:** `request_user_input`        |
| **Kiro**                                                                            | `.kiro/skills/`                                   | `node scripts/install.mjs kiro`        | ⚠️ **Text Fallback:** tool not documented |
| **Augment Code**                                                                    | `.augment/skills/`                                | `node scripts/install.mjs augment`     | ⚠️ **Text Fallback:** tool not documented |

*Skill paths follow the cross-vendor* [*Agent Skills spec*](https://agentskills.io/specification)*. Cline reads `.claude/skills/`, Junie reads `.junie/skills/`, Kiro reads `.kiro/skills/`, Augment reads `.augment/skills/`, others use `.agents/skills/`.*

#### What ports where

| Part                                      | Portable?                                                                                                                                                                                                                                                                                                                           |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The 9 skills (the audits)                 | ✅ All targets natively via Agent Skills spec                                                                                                                                                                                                                                                                                        |
| Interactive choice menus (`ask_question`) | ✅ Native question tools on most agents; text fallback on Goose/Amp/Junie                                                                                                                                                                                                                                                            |
| Sub-agent fan-out + tiers                 | ✅ Supported if host has sub-agent system; inline fallback                                                                                                                                                                                                                                                                           |
| rot-canary **auto-cadence**               | ✅ Auto-wired on Claude Code; 🔧 primed on Antigravity via the built `plugin/` folder or a one-time `hooks.json` copy (see Install) + manual snippets in [`platform-configs/hooks/`](https://github.com/TheColliery/CoalMine/tree/main/platform-configs/hooks/README.md) for other hook-capable agents; ⛔ unsupported on Cline/Junie |

**Manual Fallback:** Copy conformed skill body from [`plugin/skills/<name>/SKILL.md`](https://github.com/TheColliery/CoalMine/tree/main/plugin/skills/README.md) (strip YAML frontmatter) into `AGENTS.md` / rules file.

***

### 🚀 Install

**Node.js 22 or 24 is needed** for Option B and for the `node scripts/install.mjs` routes below (the versions CI tests; 18 and 20 are end of life). The claude.ai ZIP route needs no Node. The Claude Code plugin's hooks run `node`; on Windows without Node on your PATH, install the PowerShell fallback in `alt/powershell/` by hand (its two rot-canary hooks; the conductor needs Node).

**Per-platform, at a glance** — every canary is a read/analyze skill, so it runs wherever a `SKILL.md` loads; only the `rot-canary` auto-cadence hook is host-dependent (Claude Code auto-wires it; a manual snippet covers other hook-capable hosts).

| Platform                                              | Tier                                             | Install                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Claude Code**                                       | validated                                        | `/plugin marketplace add TheColliery/CoalMine` → `/plugin install coalmine@coalmine` (Option A) — auto-wires the `rot-canary` Stop-hook                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Antigravity**                                       | validated (canaries) · **primed** (auto-cadence) | file-copy the skills to the global `~/.gemini/config/skills/` **or** per-project `<workspace>/.agents/skills/` (clone the repo, then from **your project's root** run `node /path/to/CoalMine/scripts/install.mjs antigravity`, which writes `./.agents/skills/`); for the full auto-cadence (conductor + rot-canary) on AG 2.0's hook engine, copy the built `plugin/` folder to `<workspace>/.agents/plugins/coalmine` (measured 2026-10-09, below) or copy [`platform-configs/hooks/antigravity-hooks.json`](https://github.com/TheColliery/CoalMine/tree/main/platform-configs/hooks/antigravity-hooks.json) to `<workspace>/.agents/hooks.json` or `~/.gemini/config/hooks.json` and adjust the CoalMine path |
| **Cursor · Codex · Cline · Copilot · Gemini CLI · …** | works with                                       | clone the repo, then from **your project's root** run `node /path/to/CoalMine/scripts/install.mjs <agent>` (steps: Option B below) — file-copy into the agent's skills folder (targets in [Universal Agent Support](#-universal-agent-support))                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **claude.ai** (web / app)                             | upload confirmed 2026-10-09 (`rot-canary.zip`)   | Download the ZIP of the canary you want (`rot-canary.zip` if unsure) from [Releases](https://github.com/TheColliery/CoalMine/releases) and upload it as a custom skill (Option A3; Customize > Skills) — read/analyze skills only, manual invocation, no hooks. Confirmed 2026-10-09 by uploading `rot-canary.zip` (the v3.22.2 asset, one of nine ZIPs built the same way) in two accounts: accepted, security scan passed, listed under "Created by you". Not tested: a lower-case `skill.md`, the 201-byte description case (`telemetry-canary`), and the other eight ZIPs                                                                                                                                      |

**primed** (the Antigravity auto-cadence status — a feature-automation marker, never a platform-trust tier; Antigravity's own platform tier is `validated` above, independent of this) = built + hermetically tested against the AG 2.0 hook spec (corroborated against the official docs 2026-07-13). **Firing itself is UNRESOLVED, not confirmed:** a 2026-07-12 pilot fired CoalMine's Stop cadence live on AG; a more isolated 2026-08-04 re-test on a real AG 2.0 install recorded ZERO fires across a real tool call. Neither measurement is retracted — see [`antigravity-hooks.json`](https://github.com/TheColliery/CoalMine/tree/main/platform-configs/hooks/antigravity-hooks.json)'s own `$comment` — probe a copy of your own config before relying on it. Delivery of the injected context into the agent is separately unconfirmed end-to-end even when firing does occur. The 9 canaries themselves are already validated on AG — skill invocation, not the auto-cadence hooks, is what that covers.

**Antigravity native plugin folder (measured 2026-10-09).** Copy the built `plugin/` folder (not the repository root, whose `skills/` are unrendered templates) to `<project>/.agents/plugins/coalmine`. It carries `plugin.json` and `hooks.json`. Measured on agy 1.3.2, Windows, headless `agy -p`, in a throwaway project: the conductor line reached the model (a control without the plugin received none), the nine skills were listed, and `rot-canary` was read. With a global skills mirror (`.gemini/config/skills` in the home folder) also present, each CoalMine skill is listed twice. **Not measured:** `agy plugin install <git url>` (not supported: the repository root has no manifest), the interactive IDE, `PostToolUse` and `Stop` firing on a live run and AG acting on the Stop `continue` (no edit was made in the proof; their output shapes are pinned by unit tests), and the `commands/` (the two commands have no AG surface on this route). The AG manifest keeps the shell-string `command` form (`node hooks/<file> <Event>`), unlike the Claude Code hooks, which use the exec form (`command: node` with `args`): measured on agy 1.3.2, the exec form fired the conductor in 0 of 3 runs and the shell string in 2 of 2. One more run (2026-10-14, n = 1) put a decoy `hooks/coalmine-conductor.js` in the session folder: the shipped conductor line reached the model and the decoy did not, so Antigravity resolves the manifest's relative hook command against the plugin folder.

**Antigravity plugin facts (agy 1.4.8, 2026-10-27; the instrument is `agy plugin validate` on the dist, not a live Antigravity session).** Antigravity never loads `commands/`; `agy plugin install` converts the two commands into skills, as its own warning says ("plugins have no commands. Make each one a skill in skills//SKILL.md (`plugin install` converts Claude Code and Gemini CLI commands)"). It reads plugin hooks only from the root `hooks.json` that this folder carries, and ignores `hooks/hooks.json`. `agy plugin validate` counts the `coalmine-scanner` agent from 3.23.6; before that it skipped the agent for its `tools:` string. No live Antigravity session has spawned it.

#### Option A — Claude Code Plugin (No clone needed)

```
/plugin marketplace add TheColliery/CoalMine
/plugin install coalmine@coalmine
```

The plugin's hooks need Claude Code 2.1.139 or later (the exec form).

> 🔧 **Maintainers:** `plugin/` is generated output. After edits in `skills/`, `skills/_shared/`, `hooks/`, or `.claude-plugin/plugin.json`, run `node scripts/build-plugin.mjs`.

#### Option A2 — skills.sh (One line)

```bash
npx skills add TheColliery/CoalMine/plugin
```

Installs the 9 rendered skills from `plugin/skills/` as files: manual invocation only, no hooks. Point it at `/plugin`. The bare `TheColliery/CoalMine` form installs the unrendered `skills/` templates. Confirmed by a run on 2026-11-04 with `skills` 1.7.6, adding `--skill '*' --agent claude-code --copy -y` to the command above: 38 of 38 installed files were byte-identical to `plugin/skills` (checked with `git hash-object` per file).

#### Option A2b — APM (skills, agent and commands; hooks cannot run)

```bash
apm install TheColliery/CoalMine/plugin --target claude
```

Measured with `apm-cli` 0.35.0 from PyPI (the `microsoft/apm` project): installs the rendered skills, the agent and the 2 commands. **The hooks cannot run.** APM writes them into `.claude/settings.json`, but APM 0.35.0 rewrites `${CLAUDE_PLUGIN_ROOT}` only in a hook's command-string keys (`command`, `bash`, `powershell`, `windows`, `linux`, `osx`), and CoalMine's hooks use the exec form (`"command": "node"`, the path in `args`). In one run (2026-11-04, WSL Ubuntu, Claude Code 2.1.318) the SessionStart hook ended with exit 1 and Claude Code's own message, "Failed to run: Hook command references ${CLAUDE\_PLUGIN\_ROOT} but the hook is not associated with a plugin", no touch marker was written, and the Stop hook reported an error; the session itself carried on. Option A's plugin install (`claude plugin install coalmine@coalmine`) ran all three hooks in the same setup. Use Option A if you want the hooks. The bare `TheColliery/CoalMine` form is not a path to use: it installs the unrendered `skills/` templates and writes two hook sets into `.claude/settings.json`. One run each; this path carries no platform-tier word (validated or "works with").

#### Option A3 — claude.ai (web / desktop app)

Download a canary's ZIP from the [Releases page](https://github.com/TheColliery/CoalMine/releases) (one asset per skill, built by CI on every tag) and upload it as a custom skill, then turn it on under **Customize > Skills** in claude.ai or the desktop app (the path Anthropic's skills guide documents). Each ZIP is named after its canary (`rot-canary.zip` holds `rot-canary`): take the one for the check you want, or start with `rot-canary.zip`, the general code-health scan and the ZIP confirmed by upload. Manual invocation only — no hooks there. **Status: confirmed 2026-10-09 by uploading `rot-canary.zip`** (the v3.22.2 asset; one of the nine ZIPs, all built the same way) in two accounts. claude.ai accepted it, the security scan passed, and it is listed under "Created by you" with its name and description. The upload box says a `.zip` or `.skill` file must include a `SKILL.md`, and that the `.md` file must hold the skill name and description as YAML; the upper-case `SKILL.md` passed, `skill-meta.json` caused no refusal, and the description is read decoded (rot-canary's quoted triggers showed as real quotes). The synced skill reached a Claude Code session as `anthropic-skills:rot-canary` within minutes. **Not tested:** a lower-case `skill.md`, the 201-byte description case (`telemetry-canary`), and the other eight ZIPs (not uploaded). Anthropic's guide says the ZIP must hold the skill's folder at its top level, so the archive contains `<skill-name>/SKILL.md`, and that a `SKILL.md` at the root of the ZIP is not recognized as a skill. CoalMine's CI zips each skill folder from its parent and checks every archive entry before upload (`scripts/build-claude-ai-zips.mjs` and the release workflow), and that workflow built the v3.22.2 asset above. One uploaded ZIP is not a platform run of the suite, so this path still carries no platform-tier word (validated or "works with"). ZIPs from Releases before this fix put `SKILL.md` at the archive root, which Anthropic's guide says is not recognized: download again. To check a ZIP yourself, run `unzip -l rot-canary.zip` (swap in your ZIP): every entry should start with `rot-canary/`. **Don't hand-zip `skills/` yourself** — those are unrendered templates (their shared sections are still markers); the Release ZIPs are built from the rendered `plugin/skills/` copies. Each ZIP carries the skill description trimmed to 200 characters, a conservative house cap (Anthropic documents 1,024), until one real upload at the longer length is on record. Each Release also carries a `SHA256SUMS.txt` covering every ZIP — you'll typically have just the one skill's ZIP, not all nine, so verify with `sha256sum --ignore-missing -c SHA256SUMS.txt` (the plain `-c` form reports the other eight as FAILED). On Windows: `$f='rot-canary.zip'; (Get-FileHash $f).Hash -ieq (Select-String $f SHA256SUMS.txt).Line.Split()[0]` (swap in the ZIP you downloaded). Steps + capability notes: [CLAUDE-AI-INSTALL](https://github.com/TheColliery/.github/blob/main/CLAUDE-AI-INSTALL.md).

**Verifying one ZIP:** `sha256sum --ignore-missing -c SHA256SUMS.txt` — the plain `-c` form prints eight `FAILED open or read` lines for the ZIPs you did not download; that is not a corrupt download.

#### Option B — Universal Installer

**1. Clone the Repository**

```bash
git clone https://github.com/TheColliery/CoalMine.git
```

**2. Run the Installer**

Run from **your project's root folder** (not inside the CoalMine clone):

```bash
cd /path/to/your-project
node /path/to/CoalMine/scripts/install.mjs <agent|all|PATH>
```

* Supported `<agent>`: `antigravity`, `cursor`, `codex`, `cline`, `copilot`, `windsurf`, `amp`, `goose`, `junie`, `gemini`, `kiro`, `augment` (for `claude`, prefer the plugin above) — see [Universal Agent Support](#-universal-agent-support) for target folders + choice-tool support.
* `all` auto-detects and installs to all configured agents in the directory.
* The installer puts a small pre-commit and pre-push hook where git actually reads hooks — your `core.hooksPath` if the repo sets one (a leading `~` is expanded the way git does), otherwise `.git/hooks`. That hook only runs the hook it replaced (kept beside it as `<hook>.pre-coalmine`, with its exit status and arguments passed through, and run only while it is unchanged: the installer records the backup's fingerprint, and a changed backup stops the commit with a one-line message and exit 1); it never runs CoalMine's own test and verify gate in your repo. A hook your repo tracks (husky, lefthook, a versioned `.githooks/`) is not rewritten: the installer prints `[refused] <hook>: <reason>` and exits non-zero. It also writes trigger rules and generates `.coalmine.json` config. Every write stays inside the project (or the install target you named), with two exceptions. First, the git hook goes where `core.hooksPath` points, and when that folder is outside the project (a shared hooks folder) the installer prints a `NOTE` that the change applies to every repo using it, and it will not create such a folder. Second, the record of the skill folders the installer wrote lives in your home folder, at `~/.claude/coal/coalmine/install-record.json`. A skill folder is written whole or not at all: the installer builds it in a work folder beside it (`.<skill>.coalmine-tmp-<pid>`, marked `.coalmine-installing`), checks that every expected file is there, then renames it into place, putting a previous folder back if the rename fails. A killed install leaves only a work folder, never a partial skill folder under the skill's name. The next install or uninstall removes a leftover work folder when it is a real folder directly inside the same parent, its process is gone, and it either carries the marker or is empty (a kill before the marker is written leaves an empty folder; a non-empty folder without the marker is kept). It also removes a dead installer's `.coalmine-manifest.json.coalmine-tmp-<pid>` file in the skills folder. The installer writes a skill folder only when it can show CoalMine installed it: it keeps a record of the folders it wrote (`~/.claude/coal/coalmine/install-record.json`, with each file's hash) and replaces a folder only while every file in it still matches the record. Where a target has no record yet, a folder whose files are byte-identical to what the installer would write is adopted into the record. Any other folder (one you edited, one with a file added, or one the installer did not write) is left as it is: the installer prints `[kept] <path>: <reason>` and exits 1, and you remove the whole folder, or move it aside, and run the installer again. Delete the record file to return to the byte-match check. A path that is a symbolic link, or that resolves outside it, is refused with `[refused] <path>: <reason>` and exit 1 — the installer never writes through a link ([security advisory](https://github.com/TheColliery/CoalMine/security/advisories)).

**3. Verify & Uninstall**

* **Verify:** `node /path/to/CoalMine/scripts/verify.mjs <agent|PATH>`
* **Uninstall:** `node /path/to/CoalMine/scripts/install.mjs --uninstall <agent|PATH>` — removes CoalMine's own git hooks, but never a **tracked** one: if `core.hooksPath` points at a versioned directory (e.g. a repo's own `.githooks/`) and the hook there is ours, uninstall REFUSES rather than deleting a maintainer-owned file — it prints `[refused] <hook>: <reason>` and exits non-zero; remove it yourself (e.g. `git rm <hook>`) if you want it gone. Uninstall puts your backed-up hook back (`<hook>.pre-coalmine`) only over a hook that is CoalMine's and only when the backup still matches the fingerprint the installer recorded; if you wrote a new hook there since, both files stay, it prints `[kept] <hook>: <reason>` and exits non-zero, and you merge them yourself. A skill folder is removed only when the install record names it and every file in it still matches the hash the record holds, or when the folder is empty; any other folder, including one whose files are identical to the shipped ones but which the record does not name, is kept with a `[kept]` line and a non-zero exit, and a folder is never removed because the project manifest lists it. A linked path is refused the same way on uninstall.

***

### Commands

| Command            | What it does                                                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **the 9 canaries** | See [The 9 Canaries](#-the-9-canaries) — each triggers on its own name/keywords (e.g. `/rot-canary`) or matching conversation context |
| `/coalmine:stats`  | Measurement dashboard — canary activity this session + rule-freshness status across the project's rules home                          |
| `/coalmine:update` | Self-update — check for a newer CoalMine version and offer to apply it, or set how updates are handled                                |

***

### 🔋 One button: install — the suite drives itself

Installing is the power button. The agent conducts the canaries and asks for consent before running expensive tasks:

| What                      | When it fires                                                                                                                                                                                                                                                  | Your part                                    |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **gold-standard**         | Offered once on new projects, and again when a rule's `revalidate` date passes                                                                                                                                                                                 | Run now / Queue / Skip                       |
| **rot-canary**            | Auto-scans touched files at session end (QUICK); findings end with a fix menu                                                                                                                                                                                  | Choose a fix option                          |
| **memory-drift advisory** | One quiet `systemMessage` (reaches the session transcript and an interactive user) at session end when code changed but no MEMORY.md update was recorded — not part of the scan report, never blocks; needs a root MEMORY.md, off via `memoryDriftNudge=false` | Update MEMORY + crystallize if worth keeping |
| **Specialists**           | Offered when conversation enters their domain (deps, schemas, async, loops, etc.)                                                                                                                                                                              | Accept / Skip                                |
| **source-grounding**      | Standing rule for version-sensitive facts: always on where your `CLAUDE.md` or `AGENTS.md` carries it, offered at session start, `/source-grounding` on demand                                                                                                 | —                                            |

*Consent Rule:* Nothing expensive runs silently. Revocable via `.coalmine.json`, `~/.claude/.rot-canary-off`, or `--uninstall`.

***

### ⚙️ Configure (.coalmine.json)

Zero-config to start — and two config levels when you want them: a global `~/.claude/.coalmine.json` overlaid per key by the project config (project wins), so a globally-installed CoalMine can be tuned or **shut off per project** — a project that doesn't need it stops loading (and burning tokens) there (`disabledCanaries: ["all"]` is the full off-switch; `enableConductor: false` silences only the session-start conductor, leaving rot-canary's auto-scan running).

**Where the per-project config lives — the read order (identical across the series, one flock):** (1) `<project>/.<the running agent's own dir>/coal/coalmine.json` — the dir of the agent actually executing (Claude Code: `.claude`, i.e. `<project>/.claude/coal/coalmine.json` — the canonical path); (2) other known agent dirs, fixed order `.claude` → `.agents` → `.gemini` (first found wins); (3) LEGACY, both **DEPRECATED**: `<project>/.claude/.coalmine.json`, then `<project>/.coalmine.json` at the project root (the pre-2026-08-08 shape) — first found wins after the three above, both still read normally, no breakage for an existing config. **Deprecation notice:** the replacement is the canonical path `<project>/.claude/coal/coalmine.json`; both legacy paths are deprecated as of the release named by the `### Deprecated` entry in [CHANGELOG.md](/tools/changelog.md) and removable no earlier than the next MAJOR (deprecated at a MINOR, removable at a MAJOR — this series' SemVer boundary, not a calendar window); CoalMine owns the migration (`configure.mjs`, below). **No runtime warning is printed:** hooks stay silent (Phoenix #13), so nothing appears in your terminal — this note and the CHANGELOG are the channel. The one runtime signal is a single line in the session-start conductor's context asking the agent to relay the move, and a config sitting at a path the walk never reads (for example `<project>/.agents/.coalmine.json`) is reported the same way as IGNORED, since its settings have no effect. The installer generates the default at the new own-dir home for a never-configured project (an existing config at any candidate, including either legacy path, is left alone); `node scripts/configure.mjs` writes back wherever the config was found, migrating a legacy-location config to the new own-dir home on that write (nothing is auto-moved on a mere read). Write the global layer with `node scripts/configure.mjs --global <flags>`. The high-impact keys:

| Key                | Default | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `language`         | `auto`  | Language for prompts and nudges (`auto` \| `en` \| `th` \| `ja` \| `zh` \| `es`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `enableConductor`  | `true`  | Master switch for rules injection at session start                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `rotCanaryMode`    | `auto`  | rot-canary session-end auto-scan (`auto` \| `manual` \| `off`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `updateCheckDays`  | `14`    | Days between self-update checks or reminders (1-365; a value outside that range falls back to 14)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `memoryDriftNudge` | `true`  | Quiet session-end advisory when code changed but MEMORY.md didn't — no report, never blocks (needs a root MEMORY.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `defaultTier`      | `auto`  | Force an execution tier (`Light` \| `Standard` \| `Heavy` \| `auto`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `disabledCanaries` | `[]`    | Canaries to disable (e.g. `["rot-canary"]` or `["all"]`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `scanExcludePaths` | `[]`    | Path fragments/globs (`*` wildcard, `/` separator on every OS), matched against the project-relative path, so `**/scratchpad/**` works at any depth, skipped by the session-end auto-scan — lab tooling only (scratch probes, one-shot harnesses); shipped/tracked source is never excluded by this key                                                                                                                                                                                                                                                                                                              |
| `scanEverything`   | `false` | **The override.** `true` bypasses EVERY scan-scope cut for the run — `scanExcludePaths` ignored, `autoScanFileCap` not applied. Positive polarity: `true` = more scanning. Does NOT re-enable a disabled canary, and does not reach the recording-side cuts (`watchedExtensions`, tmpdir) or the tripwire's own `tripwireMaxFileSizeKb` cap (that file is still recorded and still scanned — only its edit-time pre-flag is skipped). **Clamped safer-value-wins:** a project-level `true` is forced to `false` unless your global layer also says `true`, so a cloned repo cannot force a full scan on your machine |

**`autoFixMode` is clamped by the hooks: a project may only lower it.** The order is `off` < `interactive` < `safe`, and `safe` counts only when it comes from your global config (`~/.claude/.coalmine.json`). A project value can keep the mode or lower it, never raise it; with no global `safe`, a project `"safe"` reads as `interactive`, so a cloned repository's `.coalmine.json` cannot turn on automatic edits. The hooks apply this on every run and say what is in effect (`[CoalMine] autoFixMode in effect: ...` on the session-start context and on the session-end scan report). A manual `/rot-canary` run has no hook in front of it: the skill text applies the same rule there, which is a mitigation an agent follows, not a clamp a machine enforces. The other keys: `updateMode`, `enableConductor`, `rotCanaryMode` and `scanEverything` are clamped the same way, and `disabledCanaries` and `scanExcludePaths` by union (a project adds to those two and never removes). Still read every project config the read order above lists (all five paths) in a clone you did not write before you open it there.

After a report, rot-canary tells the agent to sort each finding's file as a throwaway (made for one job) or an instrument (still used or shipped), to fix only instruments as the effective `autoFixMode` allows, and to offer a cleanup choice for each throwaway instead of deleting it; the agent applies this, no hook enforces it. Under `safe` or `interactive`, the Stop hook tells the agent to fix or offer fixes only when Claude Code reports a user who can answer; a headless run (`claude -p`, a child session) gets report only. A manual `/rot-canary` run still leaves that call to the agent. Other agents (Antigravity, Codex, Cursor and the rest) set no such variable, so the Stop hook and the session-start line always say report only there; run /rot-canary by hand for fix mode.

**`tempSweepStaleDays` (the age at which the Stop hook sweeps old session temp files) comes from your global config, else 7, and a project may only raise it.** A project value below the global one (or below 7 when you set none) is ignored, because a cloned repository ships its own config and a low value there would delete your session markers from every project on the machine. The minimum on either level is 1.

**Which folder counts as "the project".** The `rot-canary` Stop and touch hooks find the project config from the folder the agent started them in (their working directory), not from a workspace path in the hook's event data. The session-start conductor's Antigravity and Gemini CLI adapters do read the workspace path from the event. If your agent starts hooks in a different folder from the one you work in, put the config where the hooks' folder finds it, or use the global `~/.claude/.coalmine.json`.

**A config that exists but cannot be read.** If the project config the read order above selects, or the global config, is malformed JSON, is a directory, cannot be opened (permissions), or is valid JSON that is not an object, the session-start context carries one line in exactly this wording, and the file is skipped as if it were absent: `UNREADABLE: <path> exists but is not a readable config (<reason>); it was skipped — canonical = <canonical>`. `<reason>` is `malformed JSON`, `a directory`, `unreadable` or `not a JSON object`; `<canonical>` is the config path for that level (`.claude/coal/coalmine.json` for a project, `~/.claude/.coalmine.json` for the global file). Fix the file, or delete it, and start a new session. The line never changes which config is used, and a config refused by the link and size rule below stays silent.

**A config that is a link, or oversized.** The project config, and the rule files the conductor scans (`AGENTS.md`, `.claude/rules/**`), come with a cloned repository, so a repo can plant a link at any of those paths. The hooks read such a file only when every folder between the project root and the file is a real folder (a link at `.claude` or `.claude/coal` is refused wherever it points) and the file is a regular file, or a symlink whose target stays inside the file's own folder and is a regular file; a link that escapes that folder, a FIFO or device, or a file over 1 MiB (configs) or 4 MiB (governance docs) is **ignored** as if absent (the hooks print nothing — Phoenix #13). `node scripts/configure.mjs` **refuses** such a path instead (exit 1, the path named), never reading, backing up or overwriting through it; `--global` still writes through a link at `~/.claude/.coalmine.json`, on purpose, since dotfile managers link that file. The PowerShell fallback hooks refuse every reparse point, even one that stays inside the project. See the [security advisory](https://github.com/TheColliery/CoalMine/security/advisories).

Full key reference: every key + default lives in [`scripts/lib/config-schema.mjs`](https://github.com/TheColliery/CoalMine/tree/main/scripts/lib/config-schema.mjs) and the commented template [`platform-configs/.coalmine.json`](https://github.com/TheColliery/CoalMine/tree/main/platform-configs/.coalmine.json) — or run `node scripts/configure.mjs --help`.

### Troubleshooting

If a CoalMine hook misbehaves, switch on the debug hatch: set `COALMINE_DEBUG=1` in the shell that starts your agent, then start a new session and reproduce the fault. Each of the three Node hooks then adds two or three short lines per run to `~/.claude/coal/coalmine/debug-hatch.jsonl` (and a rotated `debug-hatch.1.jsonl`): which hook ran, which guard refused, whether it crashed and where in the hook's own code. It records structure only, never file contents or paths, and writes nothing to the screen. Unset the variable to switch it off; the files clear themselves at a later session stop once they are older than `tempSweepStaleDays` days in your global config (7 if unset), or you can delete them. The PowerShell twins in `alt/powershell/` and any install that does not use the Node hooks do not carry the hatch. One limit: the hatch needs the host to pass `COALMINE_DEBUG` on to the hooks it starts; this was measured only with a plain Node spawn, so a host that starts hooks with a cleaned environment would not pass it.

***

### Permissions

CoalMine asks for the least it needs: **read** (main + spawned scan workers, repo-scoped) · **exec** for read-only probes only (build `--dry`, lint, dead-code checks) · **scratch-write** confined to `os.tmpdir()` session state, one `~/.claude` update-check stamp and, only when you set `COALMINE_DEBUG`, the debug-hatch files under `~/.claude/coal/coalmine/` · **ask** before any fix or spend. It never requests target-file writes or deletes, and its hooks/scripts never touch the network on their own — a canary's own web check (source-grounding, CVE lookups) is the agent's own judgment call through its normal tools, not a CoalMine background call. A spawned scan worker gets strictly less than the orchestrator: no Agent or Task tool of its own, no Edit or Write tool, no prompts to the user. It does hold `Bash` for read-only probes, and a shell can write, so its read-only rule is an instruction it follows, not a sandbox. Hooks auto-wire on Claude Code and carry a tested Antigravity 2.0 contract on the same files — capability-keyed, never a hardcoded platform list.

Full series matrix + the must-fail set: [Permission Matrix](https://github.com/TheColliery/.github/blob/main/PERMISSION-MATRIX.md)

***

### 📝 Ultra-Short Summary Format

Canaries report in a lean shape (one-line verdict + severity table of confirmed findings) to save tokens. Seven canaries (all but `gold-standard`/`source-grounding`, whose output isn't per-defect) call Claude Code's `ReportFindings` panel when it's callable — click-to-file, fix-lifecycle tracking, no chat duplication; the table below is the fallback wherever the panel tool isn't available:

```
| # | path:line | category | severity | finding | evidence |
```

*Severity levels:* CRITICAL · HIGH · MEDIUM · LOW. Clean scan outputs a single line.

***

### ⚡ Escalation Tiers

| Tier         | Trigger                        | Orchestration                    | Token Cost  |
| ------------ | ------------------------------ | -------------------------------- | ----------- |
| **Light**    | Small scope / targeted review  | Primary agent, quick             | Very Low 🟢 |
| **Standard** | Moderate scope / module review | Multi-threaded routing, detailed | Moderate 🟡 |
| **Heavy**    | Large scope / release prep     | Sub-agent fan-out, deep paths    | High 🔴     |

***

### 📊 Benchmark

**Headline (measured 2026-07-03, skill v3.8.4):** 7 canaries measured over 82 fixtures (60 planted defects + 22 clean decoys) × 4 engines (Claude Fable 5 / Opus 4.8 / Sonnet 5 + Gemini 3.5 Flash), K=3-5 repeated runs per arm — **recall at 100% on 5 of 7 suites for every engine · zero decoy false alarms across the entire batch (\~200 clean-file opportunities)** · the two suites that separate engines are drift-canary (88% median — engines split on which side is authoritative) and rot-canary (92% median on opus/haiku/AG — the one item needs whole-file reachability reasoning).

Each canary is measured AV-Comparatives-style — recall, precision, decoy false-positives, and severity accuracy over fixed fixture corpora, scored mechanically, cross-engine, with repeated runs (flips extend K per the locked methodology). **Honest scope:** small, dated samples authored in-project — a regression floor, not an independent benchmark; re-run on model/skill changes.

Full method, per-category scoring, and the cross-engine comparison live in the series records: [`TheColliery/.github/benchmarks/CoalMine`](https://github.com/TheColliery/.github/tree/main/benchmarks/CoalMine).

***

### 🧭 Design Principles

Bound by the 11 principles of the [Quantum Computer Spec](https://github.com/TheColliery/.github/blob/main/DESIGN-PRINCIPLES.md): maximum performance, zero visible errors, single-brand, minimum power, essential accessories, error correction, determinism, isolation, measurement, trustworthiness, and entanglement.

***

### 🧭 Part of TheColliery

CoalMine is the quality-safeguard canary suite of a family of sibling skills built to one engineering doctrine:

* [CoalTipple](https://github.com/TheColliery/CoalTipple) — model/effort routing
* [CoalBoard](https://github.com/TheColliery/CoalBoard) — consensus & debate board
* [CoalHearth](https://github.com/TheColliery/CoalHearth) — session warm-resume
* [CoalFace](https://github.com/TheColliery/CoalFace) — fan-out discipline
* [CoalWash](https://github.com/TheColliery/CoalWash) — memory defrag
* [CoalLedger](https://github.com/TheColliery/CoalLedger) — docs health

Install one, it stands alone; install all, they compose without conflict.

Also part of the family, not yet installable: [**CoalGob**](https://github.com/TheColliery/CoalGob) (OS-trash delete guard, PUBLIC BETA v0.1.0-beta.1) — engine + tests ship, no skill/hook surface yet.

The shared doctrine: Phoenix-13 hooks (zero-dependency, no network, fail-silent, no child processes, deterministic), single-source-of-truth config schemas, and a strict no-overkill discipline. More at [TheColliery](https://github.com/TheColliery).

***

### 📄 License

Apache License 2.0. See [LICENSE](https://github.com/TheColliery/CoalMine/tree/main/LICENSE/README.md) for details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thecolliery.org/tools/coalmine.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
