git:20260929.3422014 to git:20260930.d863924

22 added, 7 removed. Audit A to A.

---

name: arch-deviate

description: "Record a deliberate deviation from the guideline as an ADR under docs/adr/: the rule quoted, the decision, the consequences. Use when a finding is accepted as intentional."

allowed-tools: Read, Grep, Glob, Write, Edit, Bash(date:*)

---

# arch-deviate

A project that follows the guideline may still need to diverge from a

rule. The divergence is recorded, not argued about in review threads:

one ADR quotes the rule, states the decision, and names what the

project accepts in exchange. A breach whose ADR is cited next to the

code is a documented exception. A review reports it on one line under

Deviations. It is not a finding, and it never lowers a severity.

## Input

The arguments name the rule being deviated from, as a lens id

(`STO-02`), a section by title (`The Storage Layer, Storage

Principles`), or a sentence describing it, optionally followed by a

one-line reason. A technology substitution (an equivalent in place of

a technology the guideline names) is not a deviation and is recorded

in the project's technology-choices ADR instead, as the guideline's

"Technology Choices and How to Override Them" section states; when

the arguments describe one, say so and stop. Ask in one

message for what is missing: the reason, the scope of the deviation

(which namespace, service, or table), and whether it is permanent or

has a condition for ending.

## Procedure

1. Resolve the rule: find the lens in `../../lenses/` and the section in

`../../architecture.md`, paths from this skill's folder as `realpath`

- resolves it. Quote the principle verbatim.

+ resolves it. Quote the principle verbatim. When the rule itself

+ allows what the arguments describe, there is nothing to record: say

+ so, quote the words that allow it, and stop. A manager interface

+ kept whole past its count because its operations are one duty is

+ such a case (CON-01): a review's pass names it.

2. The ADR goes under `docs/adr/`, created when it does not exist:

`arch-check` refuses a deviation whose `adr` is anywhere else. Number

the new record as one more than the highest numeric prefix present

(`NNNN-<slug>.md`). Refuse to write a path that already exists.

3. Take the date from `date +%F`: the ADR records the day the decision

is made, which is today, not the day of the last commit.

4. Write the ADR with the template below, under `docs/adr/` only.

Keep it under one page.

5. When `specs/architecture.md` exists and has a `## Deviations` table,

append one row: the ADR number, the rule, and a one-line summary.

- 6. When the lens has a `Check` line naming `arch-check`, the ADR alone

- does not pass the gate: the checker still fails on the code. Give

- it the entry that names the ADR, in the shape `checkers/README.md`

- in this plugin shows (`../../checkers/README.md`,

- Exceptions); the rule id is the lens id. A whole rule turned off

+ 6. An `arch-check` entry goes only with a finding the checker

+ reports. The lens's `Check` line says which part that is: the whole

+ lens when it reads "decides it", and only the part it names when it

+ ends "the rest is judged". What the line says the checker names as

+ no finding, under `to_judge`, is judged too. A deviation in a

+ judged part, or under a lens with no `Check` line, gets no entry

+ and no inline comment: the checker reports nothing there, and an

+ entry that matches no finding is itself a finding that fails the

+ gate. The ADR, the Deviations row, and the citation beside the code

+ are its record. For a deviation in the part the checker decides,

+ the ADR alone does not pass the gate: the checker still fails on

+ the code. Give it the entry that names the ADR, in the shape

+ `checkers/README.md` in this plugin shows

+ (`../../checkers/README.md`, Exceptions); the rule id is the lens

+ id. A whole rule turned off

is a `[[tool.arch-check.disable]]` entry with `rule`, `adr` (the

ADR's path), and `reason`. A rule

broken in some files is a `[[tool.arch-check.exception]]` entry

with `rule`, `path` (a glob), `adr`, and `reason`. One line is the

inline comment `# arch-check: ignore[<LENS-ID>] ADR-NNNN` at the end

of that line. Append a table entry to the root `pyproject.toml` when

it has a `[tool.arch-check]` table, and print it otherwise. Print

the inline comment and never place it: which line it goes on is the

person's call. The checker resolves an inline comment only to

`docs/adr/NNNN-*.md` with a four-digit number. When the folder's

records are numbered otherwise, give only the table entry, and say

why. Its `adr` still names a Markdown file under `docs/adr/`: the

checker refuses any other path.

7. Whatever the lens, tell the person to cite `ADR-NNNN` in a comment

beside the code that deviates. A review reports the code under

Deviations, and not as a finding, only when the ADR is cited there.

Do not commit. Do not edit the guideline or the lenses; a deviation

belongs to the project, not to the rule. Edit nothing but the ADR

folder, the deviations table, and the `[tool.arch-check]` entry.

## Output

The path of the new ADR, the row appended to the deviations table (or

"no deviations table"), the `arch-check` entry written or printed (or

- "judged by review only" when the lens has no `Check` line), the

+ "judged by review only" when the checker decides no part the deviation

+ is in), the

reminder to cite `ADR-NNNN` beside the code, and the one-line summary

for the reviewer. Nothing else.

## ADR template

```markdown

# ADR NNNN: <title that names the deviation>

**Status**: accepted (<date>)

## Context

<The rule: lens id, section, and the principle quoted verbatim. Why it

does not fit here. Facts, not preferences.>

## Decision

<What the project does instead, in the present tense. Where it applies.

Whether it is permanent or ends when a named condition holds.>

## Consequences

<What the project accepts: the guarantee it gives up, the test or check

that stands in for it, the reviews that must treat the cited code as an

exception.>

```