> 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/canaries/skill.md).

# drift-canary

Compatibility and schema drift canary — checks for database schema migration safety, breaking API contract changes, serializable payload mismatches, and backward compatibility drift. Triggers on keywo

Audit code to ensure changes do not break backward compatibility or cause database/API mismatches.

## Auditing Categories

1. **Breaking Schema Migrations** — dropping columns, changing types, or adding non-null columns without defaults (crashes on deploy).
2. **API Contract breaking changes** — modifying existing REST/GraphQL properties, removing endpoints, or adding required query fields that break old clients.
3. **Serialization mismatches** — editing properties in serialized payloads (JSON, Protobuf, XML) without deserialization fallbacks.
4. **Library Contract Drift** — changing a public method signature in a shared library without a deprecated wrapper.
5. **Environment Configuration drift** — introducing new required config keys (`.env` / OS vars) without defaults or fallback.

Expand/contract migration rules, per-format serialization fallbacks, and the breaking-vs-additive API checklist: read `references/checks.md` before scanning.

**Scope:** honor `.coalmine.json` `schemaPaths` / `migrationDirs` if set — scan those globs/dirs; else infer by inspecting the repo.

## Discipline

* **Style Drift Resolution (Fix mode):** when an approved fix touches mixed-style code, conform the minority patterns to the dominant style (highest average usage) to minimize churn — never start a standalone style refactor.

## Fix mode (choice-gated)

In Agent Context, after the report, present via `ask_question`:

* **Apply safe deprecations:** mark endpoints/methods deprecated + add backward-compatibility mapping wrappers. Each fix: checkpoint (copy the touched file(s) aside, or use an isolated worktree — never `git stash`/`git commit`, which can hide or include unrelated staged/unstaged user work) → record a build+test BASELINE → apply → build + tests → auto-revert only if a NEW failure appeared versus the baseline.
* **Let me pick:** user selects specific compatibility fixes.
* **Report only:** exit unchanged.

## Grants & denials (CLASSIFY-BLOCK)

| class | step it powers                                                                                                             | grant                                             | on denial                                                                                  |
| ----- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| read  | scan schema/API/serialization surfaces for the categories above                                                            | `Read`·`Grep`·`Glob`                              | refuse that file, name it — never a clean bill                                             |
| write | Fix mode's deprecation/compat-wrapper apply, incl. checkpoint → baseline → build+tests → auto-revert only on a NEW failure | `Edit`·`Bash` (checkpoint/build/revert need exec) | report the fix as NOT applied AND the checkpoint/revert as NOT available, never claim done |

## Output

`| file:line | contract interface | severity | finding | migration path |`

Severity: CRITICAL (breaking DB schema mutation / breaking API change) · HIGH (serialization type change) · MEDIUM (unmapped new required env key) · LOW (missing deprecation doc)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.thecolliery.org/tools/canaries/skill.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.