@arjunkhera/atlas 0.4.37 → 0.4.38

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.37",
+  "version": "0.4.38",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/door/kinds-of-change.yaml

@@ -0,0 +1,188 @@
+# The starting list of the kinds of change, for each kind of repo (roadmap R51,
+# design docs/design-docs/kinds-of-change/ in the Atlas repo). Onboarding
+# (roadmap R63) copies one list into the `kinds_of_change` key of a new repo's
+# atlas.yaml, and the repo changes it to fit its paths.
+#
+# No kind here has a `tried:` date. Locked rule 2: nothing runs alone until its
+# undo was tried once. So the gate sends each kind to the owner until the repo
+# tries its undo and writes the date and the proof.
+#
+# The first kind whose paths hold a path is its kind, so the specific kinds
+# come first. Paths match as in owner-only.yaml: a trailing `/` is a folder,
+# `*` is one name, `**/` is any depth.
+starting:
+  service:
+    - kind: Agent instructions and repo facts
+      paths: [atlas.yaml, atlas/, .claude/, CLAUDE.md, AGENTS.md, "**/CLAUDE.md", "**/AGENTS.md"]
+      impact: how every agent session works in this repo
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: CI
+      paths: [.github/]
+      impact: what runs on each pull request and on the main branch
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Tests
+      paths: [test/, tests/, "**/__tests__/", "**/*.test.*", "**/*.spec.*"]
+      impact: what the checks prove
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Schema migrations
+      paths: [migrations/, db/migrations/, "**/*.sql"]
+      impact: the data of every tenant, after the deploy runs it
+      undo: a new migration that takes the change back, merged and deployed; a dropped column or table cannot be undone
+      needs: git, gh and the deploy procedure
+    - kind: Deploy
+      paths: [deploy/, infra/, Dockerfile, "docker-compose*.yml", "*.tf"]
+      impact: where and how the service runs
+      undo: git revert -m 1 <merge commit>, merge on green, then run the deploy procedure
+      needs: git, gh and the deploy procedure
+    - kind: Service code
+      paths: [src/, app/, server/, lib/, scripts/]
+      impact: every request that the deployed service answers
+      undo: git revert -m 1 <merge commit>, merge on green, then run the deploy procedure
+      needs: git, gh and the deploy procedure
+    - kind: Dependencies
+      paths: [package.json, package-lock.json, pnpm-lock.yaml, pnpm-workspace.yaml, yarn.lock, "*.lock", go.mod, go.sum, "requirements*.txt", pyproject.toml, Cargo.toml]
+      impact: the code that builds and runs with this repo
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Docs
+      paths: [docs/, "*.md", "**/README.md"]
+      impact: what readers and agents read; no code runs it
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+  library:
+    - kind: Agent instructions and repo facts
+      paths: [atlas.yaml, atlas/, .claude/, CLAUDE.md, AGENTS.md, "**/CLAUDE.md", "**/AGENTS.md"]
+      impact: how every agent session works in this repo
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: CI
+      paths: [.github/]
+      impact: what runs on each pull request and on the main branch
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Tests
+      paths: [test/, tests/, "**/__tests__/", "**/*.test.*", "**/*.spec.*"]
+      impact: what the checks prove
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Library code
+      paths: [src/, lib/, packages/, bin/]
+      impact: every repo that takes the next release
+      undo: git revert -m 1 <merge commit>, merge on green; the release ships the old code under the next number
+      needs: git and gh only
+    - kind: Dependencies
+      paths: [package.json, package-lock.json, pnpm-lock.yaml, pnpm-workspace.yaml, yarn.lock, "*.lock", go.mod, go.sum, "requirements*.txt", pyproject.toml, Cargo.toml]
+      impact: the code that builds and runs with this repo
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Docs
+      paths: [docs/, "*.md", "**/README.md"]
+      impact: what readers and agents read; no code runs it
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+  schema:
+    - kind: Agent instructions and repo facts
+      paths: [atlas.yaml, atlas/, .claude/, CLAUDE.md, AGENTS.md, "**/CLAUDE.md", "**/AGENTS.md"]
+      impact: how every agent session works in this repo
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: CI
+      paths: [.github/]
+      impact: what runs on each pull request and on the main branch
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Tests
+      paths: [test/, tests/, "**/__tests__/", "**/*.test.*", "**/*.spec.*"]
+      impact: what the checks prove
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Schemas
+      paths: [schemas/, schema/, "**/*.schema.json", "**/*.proto", "**/*.graphql"]
+      impact: every reader and writer of the data these schemas name
+      undo: git revert -m 1 <merge commit>, merge on green, release; a removed field cannot be undone for data written meanwhile
+      needs: git and gh only
+    - kind: Schema code
+      paths: [src/, lib/, scripts/]
+      impact: how the schemas are checked and built
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Dependencies
+      paths: [package.json, package-lock.json, pnpm-lock.yaml, pnpm-workspace.yaml, yarn.lock, "*.lock", go.mod, go.sum, "requirements*.txt", pyproject.toml, Cargo.toml]
+      impact: the code that builds and runs with this repo
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Docs
+      paths: [docs/, "*.md", "**/README.md"]
+      impact: what readers and agents read; no code runs it
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+  cli:
+    - kind: Agent instructions and repo facts
+      paths: [atlas.yaml, atlas/, .claude/, CLAUDE.md, AGENTS.md, "**/CLAUDE.md", "**/AGENTS.md"]
+      impact: how every agent session works in this repo
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: CI
+      paths: [.github/]
+      impact: what runs on each pull request and on the main branch
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Tests
+      paths: [test/, tests/, "**/__tests__/", "**/*.test.*", "**/*.spec.*"]
+      impact: what the checks prove
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Command code
+      paths: [src/, cmd/, bin/, lib/, internal/]
+      impact: every person and job that installs the next release
+      undo: git revert -m 1 <merge commit>, merge on green; the release ships the old code under the next number
+      needs: git and gh only
+    - kind: Dependencies
+      paths: [package.json, package-lock.json, pnpm-lock.yaml, pnpm-workspace.yaml, yarn.lock, "*.lock", go.mod, go.sum, "requirements*.txt", pyproject.toml, Cargo.toml]
+      impact: the code that builds and runs with this repo
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Docs
+      paths: [docs/, "*.md", "**/README.md"]
+      impact: what readers and agents read; no code runs it
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+  plugin:
+    - kind: Agent instructions and repo facts
+      paths: [atlas.yaml, atlas/, .claude/, CLAUDE.md, AGENTS.md, "**/CLAUDE.md", "**/AGENTS.md"]
+      impact: how every agent session works in this repo
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: CI
+      paths: [.github/]
+      impact: what runs on each pull request and on the main branch
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Tests
+      paths: [test/, tests/, "**/__tests__/", "**/*.test.*", "**/*.spec.*"]
+      impact: what the checks prove
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Plugin
+      paths: [.claude-plugin/, skills/, agents/, hooks/, commands/, .mcp.json, "plugins/"]
+      impact: every session that loads the next release of the plugin
+      undo: git revert -m 1 <merge commit>, merge on green; the release ships the old plugin under the next number
+      needs: git and gh only
+    - kind: Plugin code
+      paths: [src/, lib/, bin/, scripts/]
+      impact: the tools and scripts the plugin runs
+      undo: git revert -m 1 <merge commit>, merge on green; the release ships the old code under the next number
+      needs: git and gh only
+    - kind: Dependencies
+      paths: [package.json, package-lock.json, pnpm-lock.yaml, pnpm-workspace.yaml, yarn.lock, "*.lock", go.mod, go.sum, "requirements*.txt", pyproject.toml, Cargo.toml]
+      impact: the code that builds and runs with this repo
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only
+    - kind: Docs
+      paths: [docs/, "*.md", "**/README.md"]
+      impact: what readers and agents read; no code runs it
+      undo: git revert -m 1 <merge commit> on a new branch, open a pull request, merge on green
+      needs: git and gh only

package/door/lib/brake.mjs

@@ -7,14 +7,21 @@
 //   windowCommits(root, base, since)                   the first-parent commits of main in the window
 //   revertTrips(root, commits)                         line 1: a revert of a change that main held
 //   ciTrips({ commits, runs, homes, ... }, jobsOf)     lines 2 and 3: a red main that a rerun confirmed, a failed live check
-//   brakeState({ root, base, now, ci })                the trips, and the date the brake ends
+//   brakeState({ root, base, now, ci })                the trips with their kinds, and the date the brake ends
 //   undoOf(root, mergeBase, head, trips)               line 4: the trip that this head undoes exactly, or null
+//   clearOf(root, base, trip, clears)                  line 6: the owner's signed clear of one trip, or null
 //
 // The brake works per repo (line 5): it reads only the history and the runs
-// of the repo that the gate judges. One signed act of the owner ends it early
-// (line 6, roadmap R72); that act does not exist yet.
+// of the repo that the gate judges. Where the repo lists its kinds of change,
+// each trip holds only the kinds of its culprit (roadmap R51, kinds.mjs).
+// Line 6: one signed act of the owner ends a trip early (roadmap R72). The act
+// is a `brake-clear` for the repo and the commit that set the trip. It sits in
+// a comment on that commit, and the key comes from atlas/owner-signers on the
+// base. So the clear is no change to atlas.yaml, and never needs the gate.
 import { spawnSync } from 'node:child_process';
 import { parseYaml } from '../../shape/check.mjs';
+import { kindsList, kindsOfCommit } from './kinds.mjs';
+import { parseSigners, verifyTexts, findAct, SIGNERS_FILE } from './signed-act.mjs';
 
 export const BRAKE_DAYS = 7;
 // A job that ends like this failed. A cancelled or skipped job did not.
@@ -142,19 +149,47 @@ export function ciTrips({ commits, runs, homes, checks, live = '', liveChecks =
   return trips;
 }
 
+// Line 6: the owner's signed clear of one trip. `clears` is { repo,
+// commentsOf(sha) }: commentsOf gives the comment texts of one commit, or
+// null when GitHub cannot say. It fails closed: no key on the base, a comment
+// that does not read, or an act for another repo or commit clears nothing.
+export function clearOf(root, base, trip, clears) {
+  if (!clears?.repo || typeof clears.commentsOf !== 'function') return null;
+  const { keys } = parseSigners(git(root, ['show', `${base}:${SIGNERS_FILE}`], { allowFail: true }) ?? '');
+  if (!keys.length) return null;
+  let texts;
+  try { texts = clears.commentsOf(trip.sha); } catch { return null; }
+  if (!Array.isArray(texts) || !texts.length) return null;
+  const found = findAct(verifyTexts(texts, keys), { kind: 'brake-clear', repo: clears.repo, commit: trip.sha });
+  return found ? { sha: trip.sha, key: found.key, signed_at: found.signed_at } : null;
+}
+
 // The brake of the repo at the base commit. `ci` holds the trips of lines 2
 // and 3, which the gate reads from GitHub; with no GitHub read it is empty.
-export function brakeState({ root, base, now = new Date(), ci = [] }) {
+// `clears` reads the owner's signed clears (line 6); a cleared trip holds
+// nothing, and the answer lists it under `cleared`.
+export function brakeState({ root, base, now = new Date(), ci = [], clears = null }) {
   const sha = fullSha(root, base);
   if (!sha) throw new BrakeError(`the base "${base}" is not a commit in this repo.`);
-  const facts = brakeFacts(git(root, ['show', `${sha}:atlas.yaml`], { allowFail: true }));
+  const text = git(root, ['show', `${sha}:atlas.yaml`], { allowFail: true });
+  const facts = brakeFacts(text);
+  const list = kindsList(text);
   const since = new Date(now.getTime() - facts.days * 864e5);
   const commits = windowCommits(root, sha, since);
   // A time after now, from an odd commit date, counts as now.
   const stamp = now.toISOString();
-  const trips = [...revertTrips(root, commits), ...ci].map((trip) => (trip.time > stamp ? { ...trip, time: stamp } : trip)).sort((a, b) => b.time.localeCompare(a.time));
+  // Each trip holds the kinds of its culprit (roadmap R51); null holds them all.
+  const all = [...revertTrips(root, commits), ...ci]
+    .map((trip) => ({ ...trip, time: trip.time > stamp ? stamp : trip.time, kinds: kindsOfCommit(root, list, trip.culprit) }))
+    .sort((a, b) => b.time.localeCompare(a.time));
+  // One clear for each commit that set a trip; a trip with no clear holds.
+  const cleared = [];
+  const bySha = new Map();
+  for (const trip of all) if (!bySha.has(trip.sha)) bySha.set(trip.sha, clearOf(root, sha, trip, clears));
+  for (const found of bySha.values()) if (found) cleared.push(found);
+  const trips = all.filter((trip) => !bySha.get(trip.sha));
   const until = trips.length ? new Date(Date.parse(trips[0].time) + facts.days * 864e5).toISOString() : null;
-  return { on: trips.length > 0, days: facts.days, since: since.toISOString(), until, trips };
+  return { on: trips.length > 0, days: facts.days, since: since.toISOString(), until, trips, cleared };
 }
 
 // The patch id of a diff, or null for an empty diff. --verbatim keeps every

package/door/lib/gate-check.mjs

@@ -16,7 +16,8 @@
 //            changed; a head that git cannot read
 //   owner    a path or a sign of the owner-only list; a head job named like a
 //            check; a refactor claim (until the review job, roadmap R28); a
-//            file too large to scan; the brake (roadmap R13, brake.mjs)
+//            file too large to scan; the brake (roadmap R13, brake.mjs); a
+//            kind of change with no tried undo (roadmap R51, kinds.mjs)
 //   success  no rule holds the pull request, or the owner signed this head
 //
 // An owner result turns into success when a comment of the pull request holds
@@ -41,13 +42,14 @@ import { listChanged } from './changed-tests.mjs';
 import { parseYaml, SECRET_PATTERNS } from '../../shape/check.mjs';
 import { parseSigners, verifyTexts, findAct, SIGNERS_FILE, BRANCH_FORM } from './signed-act.mjs';
 import { brakeState, undoOf, tripText } from './brake.mjs';
+import { kindsAt, nameKinds, kindRows } from './kinds.mjs';
 
 export const VERSION = 1;
 export const GATE_CHECK = 'gate';
 export const GATE_WORKFLOW = '.github/workflows/atlas-gate.yml';
 export const TEST_CHECKS = Object.freeze(['fails-before', 'passes-after']);
 export const RESULTS = Object.freeze(['success', 'owner', 'red']);
-export const ANSWER_KEYS = Object.freeze(['gate', 'base', 'merge_base', 'head', 'result', 'class', 'rows', 'signed_act', 'brake', 'signed']);
+export const ANSWER_KEYS = Object.freeze(['gate', 'base', 'merge_base', 'head', 'result', 'class', 'rows', 'signed_act', 'brake', 'signed', 'kinds']);
 export const SIGNED_ACT = "Clears with the owner's signed act: atlas approve <pr> (roadmap R72).";
 // A file over this size is not scanned for secrets, and comes to the owner.
 export const SCAN_LIMIT = 1024 * 1024;
@@ -275,7 +277,7 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null,
   const baseSha = commitOf(top, base);
   if (!baseSha) throw new GateCheckError(`the base "${base}" is not a commit in this repo.`);
   const headSha = commitOf(top, head);
-  const answer = { gate: VERSION, base: baseSha, merge_base: null, head: headSha || String(head), result: 'red', class: null, rows: [], signed_act: null, brake: null, signed: null };
+  const answer = { gate: VERSION, base: baseSha, merge_base: null, head: headSha || String(head), result: 'red', class: null, rows: [], signed_act: null, brake: null, signed: null, kinds: null };
   if (!headSha) {
     answer.rows.push({ kind: 'red', class: 'gate', cause: 'the head commit is not readable in this clone' });
     return finish(answer);
@@ -287,12 +289,17 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null,
   }
   answer.merge_base = mergeBase;
   const changes = changedPaths(top, mergeBase, headSha);
+  // The kind of each changed path, by the list on the base (roadmap R51).
+  const list = kindsAt(top, baseSha);
+  const named = nameKinds(list, changes.map((change) => change.path));
+  answer.kinds = { listed: list.listed, names: named.names, unlisted: list.listed ? named.unlisted : [] };
   let undo = null;
   if (brake !== false) {
-    const state = brakeState({ root: top, base: baseSha, now, ci: brake?.ci ?? [] });
+    const state = brakeState({ root: top, base: baseSha, now, ci: brake?.ci ?? [], clears: brake?.clears ?? null });
     undo = undoOf(top, mergeBase, headSha, state.trips);
-    answer.brake = { on: state.on, until: state.until, days: state.days, trips: state.trips, undo: undo?.culprit ?? null };
-    answer.rows.push(...brakeRows(state, undo));
+    answer.brake = { on: state.on, until: state.until, days: state.days, trips: state.trips, undo: undo?.culprit ?? null, cleared: state.cleared };
+    for (const one of state.cleared) answer.rows.push({ kind: 'note', class: 'brake', cause: `the owner's signed clear ended the trip set by ${one.sha.slice(0, 7)} (key ${one.key}, ${one.signed_at})` });
+    answer.rows.push(...brakeRows(state, undo, list.listed ? named : null));
   }
   // The rules come from the base commit, never from the merge base. An agent
   // picks the merge base when it picks where its branch starts, also a middle
@@ -300,6 +307,7 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null,
   // change back (item d56a9c03). The diff stays merge base to head.
   const ruleRef = rules ?? baseSha;
   for (const row of classify({ root: top, base: mergeBase, head: headSha, rules: ruleRef }).rows) answer.rows.push({ kind: 'owner', class: row.class ?? 'unlisted', path: row.path, cause: row.cause });
+  answer.rows.push(...kindRows(list, named));
   answer.rows.push(...jobRows(top, ruleRef, headSha, changes));
   answer.rows.push(...secretRows(top, mergeBase, headSha, changes));
   if (terms !== undefined) answer.rows.push(...termRows(top, baseSha, headSha, changes, terms));
@@ -428,13 +436,27 @@ function carryOne(root, baseSha, headSha, mergeBase, act) {
 }
 
 // Line 1: while the brake is on, every pull request of the repo comes to the
-// owner, except the exact undo of a trip (line 4).
-function brakeRows(state, undo) {
+// owner, except the exact undo of a trip (line 4). Where the repo lists its
+// kinds (roadmap R51), a trip holds only a pull request that shares a kind
+// with it. A trip with no kinds, or a pull request with a path of no kind,
+// holds as before.
+const holds = (trip, named) => !named || !trip.kinds || named.unlisted.length > 0 || trip.kinds.some((kind) => named.names.includes(kind));
+
+function brakeRows(state, undo, named = null) {
   if (!state.on) return [];
-  const newest = state.trips[0];
-  const more = state.trips.length > 1 ? `; ${state.trips.length} trips in ${state.days} days` : '';
+  const holding = state.trips.filter((trip) => holds(trip, named));
+  if (!undo && !holding.length) {
+    const kinds = [...new Set(state.trips.flatMap((trip) => trip.kinds))].join(', ');
+    return [{ kind: 'note', class: 'brake', cause: `the brake is on until ${state.until.slice(0, 16).replace('T', ' ')} UTC for ${kinds}; this pull request is ${named.names.join(', ') || 'no kind'}` }];
+  }
+  const newest = holding[0] ?? state.trips[0];
+  const more = holding.length > 1 ? `; ${holding.length} trips in ${state.days} days` : '';
   if (undo) return [{ kind: 'note', class: 'brake', cause: `the exact undo of ${undo.culprit.slice(0, 7)}, which tripped the brake: ${tripText(undo)}` }];
-  return [{ kind: 'owner', class: 'brake', cause: `the brake is on until ${state.until.slice(0, 16).replace('T', ' ')} UTC: ${tripText(newest)}${more}` }];
+  const until = new Date(Date.parse(newest.time) + state.days * 864e5).toISOString();
+  const owner = { kind: 'owner', class: 'brake', cause: `the brake is on until ${until.slice(0, 16).replace('T', ' ')} UTC: ${tripText(newest)}${more}` };
+  // Done line 6: one signed clear for each trip, as a comment on its commit.
+  const clear = (holding.length ? holding : [newest]).map((trip) => ({ kind: 'note', class: 'brake', cause: `to end the trip now: atlas approve act brake-clear --repo <owner/repo> --commit ${trip.sha}, then post the block as a comment on commit ${trip.sha.slice(0, 7)}` }));
+  return [owner, ...clear];
 }
 
 function finish(answer) {

package/door/lib/gate.mjs

@@ -705,6 +705,20 @@ export function prComments(gh, repo, pr) {
   return kept;
 }
 
+// The comment texts of one commit on main that carry the signed-act marker:
+// where the owner posts a brake clear (roadmap R13 line 6). At most three
+// pages of a hundred. A read that fails gives null, so no clear counts.
+export function commitComments(gh, repo, sha) {
+  const texts = [];
+  for (let page = 1; page <= 3; page += 1) {
+    const rows = gh('GET', `repos/${repo}/commits/${sha}/comments?per_page=100&page=${page}`);
+    if (!Array.isArray(rows)) return null;
+    for (const row of rows) if (typeof row?.body === 'string' && row.body.includes(SIGNED_MARKER)) texts.push(row.body);
+    if (rows.length < 100) break;
+  }
+  return texts;
+}
+
 // The base workflow files that define a job of one of `names`, read from git.
 function definedAt(git, sha, names) {
   const files = new Set();
@@ -753,7 +767,7 @@ export function gateCommand({ what, repo, root, dryRun = false, off = false, on
   const named = repo && repo !== true && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) && !repo.split('/').some((part) => /^\.+$/.test(part));
   if (what === 'check') {
     const number = /^[1-9][0-9]{0,8}$/.test(String(pr ?? '')) ? Number(pr) : null;
-    return checkCommand({ root, base, head, body, json, summary, output, repo: named ? repo : null, pr: pr === undefined ? null : pr, baseRef: baseRef ?? null }, line, named ? () => ({ redMain: redMain({ root, base }, gh, repo), brake: { ci: brakeRead({ root, base }, gh, repo) } }) : null, named && number ? () => prComments(gh, repo, number) : null);
+    return checkCommand({ root, base, head, body, json, summary, output, repo: named ? repo : null, pr: pr === undefined ? null : pr, baseRef: baseRef ?? null }, line, named ? () => ({ redMain: redMain({ root, base }, gh, repo), brake: { ci: brakeRead({ root, base }, gh, repo), clears: { repo, commentsOf: (sha) => commitComments(gh, repo, sha) } } }) : null, named && number ? () => prComments(gh, repo, number) : null);
   }
   if (what === 'replay') return replayCommand({ root, days, branch, json }, line);
   if (!named) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);

package/door/lib/kinds.mjs

@@ -0,0 +1,128 @@
+// The kinds of change (roadmap R51, tracker item d192ec7d; design
+// docs/design-docs/kinds-of-change/). Each repo lists its kinds in atlas.yaml,
+// under `kinds_of_change`: a set of paths, the impact, the undo, and the day
+// the undo was tried. The gate reads the list from the base, names the kind of
+// each changed path, and sends to the owner a kind whose undo was never tried.
+//
+//   kindsList(text)                     the list of one atlas.yaml text
+//   kindsAt(root, ref)                  the list of atlas.yaml at a commit
+//   nameKinds(list, paths)              the kind of each path: { names, byKind, unlisted }
+//   kindRows(list, named)               the gate rows of one pull request
+//   kindsOfCommit(root, list, sha)      the kind names of one commit on main, or null
+//   startingLists(text)                 the starting list for each kind of repo
+//
+// Locked rule 2 of the target design: nothing runs alone until its undo is
+// written, tried once and takes minutes. So a path that no kind holds, a kind
+// with no undo, and an undo never tried all come to the owner. A repo with no
+// list gets no kind rows: its rules stay as they were.
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from '../../shape/check.mjs';
+import { matcher } from './owner-only.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const STARTING_FILE = join(HERE, '..', 'kinds-of-change.yaml');
+export const REPO_KINDS = Object.freeze(['service', 'library', 'schema', 'cli', 'plugin']);
+// The gate names at most this many paths with no kind, then counts the rest.
+const NAMED_PATHS = 20;
+
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const triedDay = (value) => {
+  const text = String(value ?? '').trim();
+  return DAY.test(text) && !Number.isNaN(Date.parse(`${text}T00:00:00Z`)) ? text : null;
+};
+const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+
+// One list from the entries of `kinds_of_change`. An entry with no name is
+// skipped with a note. An entry with no paths holds no path.
+function fromEntries(entries) {
+  if (!Array.isArray(entries)) return { listed: false, kinds: [], notes: [] };
+  const kinds = [];
+  const notes = [];
+  entries.forEach((entry, index) => {
+    const kind = entry && typeof entry === 'object' && !Array.isArray(entry) ? text(entry.kind) : null;
+    if (!kind) { notes.push(`kinds_of_change entry ${index + 1} has no kind, so the gate skips it`); return; }
+    const paths = Array.isArray(entry.paths) ? entry.paths.filter((path) => typeof path === 'string' && path.trim()) : [];
+    if (!paths.length) notes.push(`${kind}: it lists no paths, so it holds no path`);
+    const except = Array.isArray(entry.except) ? entry.except.filter((path) => typeof path === 'string' && path.trim()) : [];
+    kinds.push({ kind, paths, except, undo: text(entry.undo), tried: triedDay(entry.tried), impact: text(entry.impact) });
+  });
+  // A list in which no kind names its paths is the form from before R51: it
+  // says nothing about paths, so the gate treats the repo as one with no list.
+  return { listed: kinds.some((one) => one.paths.length > 0), kinds, notes };
+}
+
+export function kindsList(source) {
+  let facts;
+  try { facts = parseYaml(source ?? '') ?? {}; } catch { facts = {}; }
+  return fromEntries(facts && typeof facts === 'object' ? facts.kinds_of_change : null);
+}
+
+function git(root, args) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout : null;
+}
+
+export const kindsAt = (root, ref) => kindsList(git(root, ['show', `${ref}:atlas.yaml`]));
+
+// Paths match with case here: a match grants the kind's tried undo.
+const exact = (pattern) => matcher(pattern, { caseless: false });
+
+// The first kind whose paths hold the path, and whose `except` does not.
+export function kindOf(list, path) {
+  for (const one of list.kinds) {
+    if (one.paths.some((pattern) => exact(pattern)(path)) && !one.except.some((pattern) => exact(pattern)(path))) return one;
+  }
+  return null;
+}
+
+export function nameKinds(list, paths) {
+  const byKind = new Map();
+  const unlisted = [];
+  for (const path of paths) {
+    const one = kindOf(list, path);
+    if (!one) { unlisted.push(path); continue; }
+    if (!byKind.has(one.kind)) byKind.set(one.kind, { kind: one, paths: [] });
+    byKind.get(one.kind).paths.push(path);
+  }
+  // The kinds in the order of the list, so the rows do not depend on the diff.
+  const order = (name) => list.kinds.findIndex((one) => one.kind === name);
+  const sorted = new Map([...byKind].sort(([a], [b]) => order(a) - order(b)));
+  return { names: [...sorted.keys()], byKind: sorted, unlisted };
+}
+
+// The rows of one pull request: a note for each kind it changes, and an owner
+// row for each kind that has no tried undo and for each path with no kind.
+export function kindRows(list, named) {
+  if (!list.listed) return [];
+  const rows = list.notes.map((cause) => ({ kind: 'note', class: 'kind', cause }));
+  for (const { kind, paths } of named.byKind.values()) {
+    if (!kind.undo) rows.push({ kind: 'owner', class: 'kind', cause: `${kind.kind}: it names no undo (atlas.yaml kinds_of_change)` });
+    else if (!kind.tried) rows.push({ kind: 'owner', class: 'kind', cause: `${kind.kind}: its undo was never tried (atlas.yaml kinds_of_change)` });
+    rows.push({ kind: 'note', class: 'kind', cause: `${kind.kind}: ${paths.length} path(s)${kind.tried ? `; undo tried ${kind.tried}` : ''}` });
+  }
+  for (const path of named.unlisted.slice(0, NAMED_PATHS)) rows.push({ kind: 'owner', class: 'kind', path, cause: 'no kind of change holds this path, so it has no undo' });
+  if (named.unlisted.length > NAMED_PATHS) rows.push({ kind: 'owner', class: 'kind', cause: `${named.unlisted.length - NAMED_PATHS} more path(s) that no kind of change holds` });
+  return rows;
+}
+
+// The kinds of one commit on main, by its change from its first parent. Null
+// means the brake must hold every kind: the base lists no kinds, the commit
+// has no parent here, or one of its paths has no kind.
+export function kindsOfCommit(root, list, sha) {
+  if (!list.listed) return null;
+  const out = git(root, ['diff', '--name-only', '-z', '--no-renames', `${sha}^1`, sha, '--']);
+  if (out === null) return null;
+  const named = nameKinds(list, out.split('\0').filter(Boolean));
+  return named.unlisted.length || !named.names.length ? null : named.names;
+}
+
+// The starting list for each kind of repo, as packages/atlas/door/kinds-of-change.yaml
+// holds it. Onboarding (roadmap R63) copies one into the new repo's atlas.yaml.
+export function startingLists(source = readFileSync(STARTING_FILE, 'utf8')) {
+  const facts = parseYaml(source) ?? {};
+  const starting = facts.starting && typeof facts.starting === 'object' ? facts.starting : {};
+  return Object.fromEntries(REPO_KINDS.map((repoKind) => [repoKind, fromEntries(starting[repoKind] ?? [])]));
+}

package/door/lib/owner-only.mjs

@@ -85,8 +85,10 @@ const escape = (text) => text.replace(/[.+^${}()|[\]\\]/g, '\\$&');
 
 // A pattern of owner-only.yaml or atlas.yaml. `**/` is any depth, `*` is one
 // name, `?` one character, and a trailing `/` is a folder. It matches with no
-// case and on whole names: `door/` never matches `door-x/`.
-export function matcher(pattern) {
+// case and on whole names: `door/` never matches `door-x/`. The kinds of change
+// pass `caseless: false`: there a match grants a tried undo, so `ENGINE/` must
+// not take the undo of `engine/`.
+export function matcher(pattern, { caseless = true } = {}) {
   const folder = pattern.endsWith('/');
   const body = clean(pattern);
   let out = '';
@@ -98,7 +100,7 @@ export function matcher(pattern) {
     if (character === '?') { out += '[^/]'; continue; }
     out += escape(character);
   }
-  const regex = new RegExp(`^${out}${folder ? '/.+' : '(?:/.+)?'}$`, 'i');
+  const regex = new RegExp(`^${out}${folder ? '/.+' : '(?:/.+)?'}$`, caseless ? 'i' : '');
   return (path) => regex.test(clean(path));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.37",
+  "version": "0.4.38",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",