@arjunkhera/atlas 0.4.1 → 0.4.3

package/.claude-plugin/plugin.json

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

package/README.md

@@ -4,7 +4,7 @@ Atlas sets how a repository is worked on. It is one Claude Code plugin with:
 
 1. **The lead**, `atlas:lead`: the talk rules, the routing and the command
    list. It loads on its own in each session of a repo with `atlas.yaml`.
-   No one has to call it.
+   Nobody has to call it.
 2. **The rulebook**, `atlas:sdlc-task`: start, pause, resume, lock and finish
    one piece of work. Three more skills: `repo-skills` adds a procedure the
    right way, `learnings` turns a miss into one fix, and `feedback` files an

package/door/lib/gate.mjs

@@ -15,8 +15,9 @@
 // The plan is built by pure functions, so a test reads it without GitHub. The
 // gh calls sit in one place, behind `gh`, which a test replaces.
 import { execFileSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { parseYaml } from '../../shape/check.mjs';
 
@@ -195,9 +196,10 @@ const checkLine = (row) => `  ${row.state === 'green' ? '✓' : '✗'} ${row.sta
 
 // `atlas gate ready --pr <n>`: may this pull request merge now? Exit 0 when
 // every required check is green on its head commit, 1 when not.
-export function readyCommand({ repo, pr }, line, gh = ghApi) {
+export function readyCommand({ repo, pr, answer }, line, gh = ghApi) {
   if (!pr || pr === true || !/^\d+$/.test(String(pr))) throw new GateError('atlas gate ready needs --pr <number>.');
   const pull = gh('GET', `repos/${repo}/pulls/${pr}`);
+  if (answer && typeof pull?.head?.sha === 'string') answer.sha = pull.head.sha;
   if (pull?.state !== 'open') { line(`atlas gate ready: pull request #${pr} is ${pull?.merged ? 'merged' : pull?.state ?? 'not found'}. NOT READY.`); return 1; }
   const sha = pull.head.sha;
   const checks = checksAt(gh, repo, pull.base.ref);
@@ -209,6 +211,24 @@ export function readyCommand({ repo, pr }, line, gh = ghApi) {
   return ready ? 0 : 1;
 }
 
+// The merge door hook (packages/atlas/hooks/door.mjs) reads this file before
+// a merge. It holds the last READY of one pull request: the repo, the number,
+// the head commit and the time. Any answer but READY removes the file, so an
+// old READY never outlives a newer NOT READY. The hook keeps its own copy of
+// the path, because its bytes are pinned.
+export const readyFile = (repo, pr, home = homedir()) => join(home, '.config', 'atlas', 'gate-ready', ...repo.toLowerCase().split('/'), String(pr));
+
+export function keepReady({ repo, pr, sha, code, home = homedir(), now = new Date() }) {
+  if (repo.split('/').some((part) => /^\.+$/.test(part))) return null;
+  const path = readyFile(repo, pr, home);
+  if (code !== 0 || !/^[0-9a-f]{40}$/i.test(String(sha ?? ''))) { rmSync(path, { force: true }); return null; }
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify({ repo: repo.toLowerCase(), pr: Number(pr), sha: sha.toLowerCase(), at: now.toISOString() })}\n`, { mode: 0o600 });
+  renameSync(temp, path);
+  return path;
+}
+
 // `atlas gate audit --since <date>`: each pull request merged since the date
 // whose required checks were not all green at the moment of the merge.
 export function auditCommand({ repo, since, commit }, line, gh = ghApi) {
@@ -275,10 +295,22 @@ function commitAudit({ repo, commit }, line, gh) {
 }
 
 // `atlas gate apply|ready|audit`. Returns the exit code.
-export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit }, line, gh = ghApi) {
+export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, home = homedir() }, line, gh = ghApi) {
   if (!['apply', 'ready', 'audit'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready or audit.`);
   if (!repo || repo === true || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);
-  if (what === 'ready') return readyCommand({ repo, pr }, line, gh);
+  if (what === 'ready') {
+    const answer = {};
+    let code = 1;
+    try { code = readyCommand({ repo, pr, answer }, line, gh); } finally {
+      if (/^\d+$/.test(String(pr ?? ''))) {
+        try {
+          const kept = keepReady({ repo, pr, sha: answer.sha, code, home });
+          if (kept) line(`The merge door may merge #${pr} at this head for ten minutes.`);
+        } catch (error) { line(`The merge door could not keep this answer (${error.code ?? error.message}), so it will refuse the merge. Run ready again outside the sandbox.`); }
+      }
+    }
+    return code;
+  }
   if (what === 'audit') return auditCommand({ repo, since, commit }, line, gh);
   if (off && on) throw new GateError('pick --off or --on, not both.');
   const mode = off ? 'off' : on ? 'on' : 'apply';

package/hooks/door.mjs

@@ -0,0 +1,387 @@
+// The merge door: the second hook Atlas ships. Claude Code runs it before a
+// tool call that can merge, push or write a file. On a plan with no
+// rulesets GitHub blocks nothing, so this hook holds the gate in a session
+// (design docs/design-docs/gate-advisory/, done line 8).
+//
+// It refuses five things, and lets every other call through:
+// 1. A merge or an auto-merge, through a GitHub tool or `gh pr merge`, unless
+//    `atlas gate ready` said READY for that pull request in the last ten
+//    minutes, and the merge names the same head commit. The auto-merge tool
+//    cannot name a head, so it is always refused.
+// 2. A merge through another door: `gh api` on a merge path, a GraphQL merge,
+//    `gh pr merge --admin`, or a plain HTTP call to a GitHub merge path.
+// 3. A push to the default branch, a force push, and a push of all branches.
+// 4. A file write to the default branch through a GitHub tool.
+// 5. A change to the READY answers, a change to a Claude settings file by a
+//    command or to its hook and plugin switches, and turning the plugin off.
+//
+// Its limits:
+// 1. It makes no network call and starts no program. It reads the tool call,
+//    the READY answer file, and the git folder of the repo it pushes from.
+// 2. It writes nothing. It never answers "allow": a call it lets through
+//    still goes to the person's own permission rules.
+// 3. It matches text. A command it cannot read as a push or a merge goes
+//    through. The push audit job and `atlas gate audit` stay the backstop.
+// 4. ATLAS_HOOKS=off, set outside the session, turns it off.
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const FRESH_MS = 10 * 60 * 1000;
+export const DEFAULTS = ['main', 'master'];
+const SHA = /^[0-9a-f]{40}$/i;
+
+// The folder where `atlas gate ready` keeps each READY answer.
+export const readyFolder = (home = homedir()) => join(home, '.config', 'atlas', 'gate-ready');
+export const readyPath = (repo, pr, home = homedir()) => join(readyFolder(home), ...String(repo).toLowerCase().split('/'), String(pr));
+
+// ------------------------------------------------------------------ the door
+
+// One tool call in, one answer out: null lets it through, a string refuses it.
+export function judge(call, { home = homedir(), now = Date.now() } = {}) {
+  const tool = String(call?.tool_name ?? '');
+  const input = call?.tool_input ?? {};
+  const cwd = typeof call?.cwd === 'string' ? call.cwd : process.cwd();
+  if (tool === 'Bash') return judgeCommand(String(input.command ?? ''), { cwd, home, now });
+  if (['Write', 'Edit', 'MultiEdit', 'NotebookEdit'].includes(tool)) return judgeWrite(input, { cwd, home });
+  if (!tool.startsWith('mcp__')) return null;
+  const verb = tool.slice(tool.lastIndexOf('__') + 2);
+  const repo = `${input.owner ?? ''}/${input.repo ?? ''}`;
+  if (verb === 'merge_pull_request') return needReady({ repo, pr: input.pullNumber, sha: input.expectedHeadSha, home, now, how: 'the expectedHeadSha argument' });
+  // This tool cannot name the head, so a later push could merge with no READY.
+  if (verb === 'enable_pr_auto_merge') return 'the merge door refuses enable_pr_auto_merge: it cannot name the head that ready read. Run "atlas gate ready", then merge with the head SHA, or use "gh pr merge --auto --match-head-commit <sha>".';
+  if (['push_files', 'create_or_update_file', 'delete_file'].includes(verb)) {
+    const branch = String(input.branch ?? '').replace(/^refs\/heads\//, '');
+    if (!branch) return `the merge door refuses ${verb} with no branch: GitHub would write to the default branch. Name a work branch.`;
+    if (defaultsFor(repo, cwd).has(branch)) return `the merge door refuses ${verb} on ${branch}, the default branch. Write to a work branch and open a pull request.`;
+  }
+  return null;
+}
+
+// A merge waits for a fresh READY at the same head.
+function needReady({ repo, pr, sha, home, now, how }) {
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || repo.split('/').some((part) => /^\.+$/.test(part)) || !/^\d+$/.test(String(pr ?? ''))) return 'the merge door refuses a merge that does not name its repo and pull request number.';
+  const run = `atlas gate ready --repo ${repo} --pr ${pr}`;
+  let answer;
+  try { answer = JSON.parse(readFileSync(readyPath(repo, pr, home), 'utf8')); } catch {
+    return `the merge door refuses the merge of ${repo}#${pr}: there is no READY answer for it. Run "${run}" right before the merge.`;
+  }
+  const at = Date.parse(answer?.at ?? '');
+  if (String(answer?.repo ?? '').toLowerCase() !== repo.toLowerCase() || String(answer?.pr) !== String(pr) || !SHA.test(String(answer?.sha ?? '')) || Number.isNaN(at)) {
+    return `the merge door refuses the merge of ${repo}#${pr}: its READY answer is not well formed. Run "${run}" again.`;
+  }
+  if (now - at > FRESH_MS || at - now > 60 * 1000) return `the merge door refuses the merge of ${repo}#${pr}: its READY answer is older than ten minutes. Run "${run}" again.`;
+  if (!sha) return `the merge door refuses the merge of ${repo}#${pr}: name the head that ready read (${answer.sha}) in ${how}.`;
+  if (String(sha).toLowerCase() !== answer.sha.toLowerCase()) return `the merge door refuses the merge of ${repo}#${pr}: the merge names ${String(sha).slice(0, 7)}, but ready read ${answer.sha.slice(0, 7)}. Run "${run}" on the new head.`;
+  return null;
+}
+
+// ------------------------------------------------------------- file writes
+
+const SWITCH = /ATLAS_HOOKS|disableAllHooks|enabledPlugins|atlas@|"hooks"\s*:/;
+// A command with one of these words can write a file.
+const WRITES = /(>|\b(tee|cp|mv|touch|rm|mkdir|ln|chmod|install|rsync|dd|truncate|node|python3?|perl|ruby|jq)\b|\bsed\b[^|;&]*\s-i)/;
+const SETTINGS = /(^|[\\/])\.claude[\\/]settings(\.local)?\.json$/;
+
+function judgeWrite(input, { cwd, home }) {
+  const raw = String(input.file_path ?? input.notebook_path ?? '');
+  if (!raw) return null;
+  const path = resolve(cwd, raw.replace(/^~(?=[\\/])/, home));
+  const ready = readyFolder(home);
+  if (path === ready || path.startsWith(ready + '/') || path.startsWith(ready + '\\')) return 'the merge door refuses a write to the READY answers (~/.config/atlas/gate-ready): only "atlas gate ready" writes them.';
+  if (SETTINGS.test(path)) {
+    // The old text counts too: an edit of true to false names no switch word.
+    const text = [input.content, input.old_string, input.new_string, ...(input.edits ?? []).flatMap((edit) => [edit?.old_string, edit?.new_string])].filter((part) => typeof part === 'string').join('\n');
+    if (SWITCH.test(text)) return 'the merge door refuses a change to the hooks or the plugins in a Claude settings file. Only the person turns the Atlas hooks off, outside the session.';
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------- commands
+
+// Split a command line into simple commands, and each one into words. Quotes
+// and backslashes are read the way the shell reads them. A `(` ends a command
+// too. judgeCommand reads the inside of each `$(...)` and backtick pair again,
+// since a shell runs it even inside double quotes.
+export function commandsOf(text) {
+  const out = [];
+  let words = [];
+  let word = null;
+  const endWord = () => { if (word !== null) words.push(word); word = null; };
+  const endCommand = (op) => { endWord(); if (words.length) out.push({ words, op }); words = []; };
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (c === "'") { const end = text.indexOf("'", i + 1); word = (word ?? '') + text.slice(i + 1, end < 0 ? text.length : end); i = end < 0 ? text.length : end; continue; }
+    if (c === '"') {
+      word = word ?? '';
+      for (i += 1; i < text.length && text[i] !== '"'; i += 1) word += text[i] === '\\' && i + 1 < text.length ? text[++i] : text[i];
+      continue;
+    }
+    if (c === '\\' && i + 1 < text.length) { if (text[i + 1] !== '\n') word = (word ?? '') + text[i + 1]; i += 1; continue; }
+    if (c === '\n' || c === ';' || c === '&' || c === '|' || c === '(' || c === ')') { endCommand(c); continue; }
+    if (c === ' ' || c === '\t') { endWord(); continue; }
+    if (c === '#' && word === null) { const end = text.indexOf('\n', i); i = end < 0 ? text.length : end - 1; continue; }
+    word = (word ?? '') + c;
+  }
+  endCommand('');
+  return out;
+}
+
+// Leading words that run the next word as the command. `timeout` also takes
+// a time. A command named by its full path counts by its last name.
+const WRAPPERS = new Set(['sudo', 'command', 'exec', 'nohup', 'time', 'env', 'builtin', 'xargs', 'nice', 'timeout', 'stdbuf']);
+const baseName = (word) => String(word ?? '').replace(/^.*\//, '');
+function commandWords(words) {
+  let i = 0;
+  for (;;) {
+    const word = words[i];
+    if (word === undefined) break;
+    if (WRAPPERS.has(baseName(word))) {
+      i += 1;
+      while (words[i]?.startsWith('-')) i += 1;
+      if (baseName(word) === 'timeout' && /^\d/.test(words[i] ?? '')) i += 1;
+      continue;
+    }
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) { i += 1; continue; }
+    break;
+  }
+  const out = words.slice(i);
+  if (out.length) out[0] = baseName(out[0]);
+  return out;
+}
+
+// The text a shell reads for `$(...)` and backticks: without single-quoted
+// strings and without here-documents whose end word is quoted.
+const unquoted = (text) => text.replace(/<<-?\s*(['"])(\w+)\1[^\n]*\n[\s\S]*?\n\s*\2(?=\n|$)/g, ' ').replace(/'[^']*'/g, "''");
+// The command lines only: a here-document body is data for its command.
+const noHereDocs = (text) => text.replace(/<<-?\s*(['"]?)(\w+)\1([^\n]*)\n[\s\S]*?\n\s*\2(?=\n|$)/g, ' $3');
+
+const GH_MERGE_PATH = /(^|\/)repos\/[^/\s]+\/[^/\s]+\/(pulls\/\d+\/merge|merges)\b|(^|\/)pulls\/\d+\/merge\b/;
+const GH_REFS_PATH = /(^|\/)git\/refs\b/;
+const GQL_MERGE = /\b(mergePullRequest|enablePullRequestAutoMerge|mergeBranch|updateRefs?|deleteRef)\b/;
+const HTTP_MERGE = /api\.github\.com\/repos\/[^\s'"]+\/(pulls\/\d+\/merge|merges|git\/refs)/;
+
+function judgeCommand(text, { cwd, home, now }) {
+  // 5. The READY answers, the key and the hook switch are not the session's
+  //    to change, by any command.
+  if (/gate-ready/.test(text) && WRITES.test(text)) return 'the merge door refuses a command that names the READY answers (~/.config/atlas/gate-ready) and can write a file: only "atlas gate ready" writes them.';
+  if (/\.claude[\\/]settings(\.local)?\.json/.test(text) && (SWITCH.test(text) || WRITES.test(text))) return 'the merge door refuses a command that changes a Claude settings file. The person changes the hooks and the plugins, outside the session.';
+  if (/\bclaude\s+plugins?\s+(disable|uninstall|remove)\b[^|;&]*\batlas\b/.test(text)) return 'the merge door refuses to turn the Atlas plugin off. The person runs that command, outside the session.';
+  if (HTTP_MERGE.test(text) && /\b(curl|wget|fetch|http|requests|urllib)\b/.test(text)) return 'the merge door refuses a merge or a branch write through a plain call to the GitHub API. Merge with the GitHub merge tool or "gh pr merge", after "atlas gate ready" says READY.';
+  for (const [, inner] of [...unquoted(text).matchAll(/\$\(([^()]*)\)|`([^`]*)`/g)].map((match) => [match[0], match[1] ?? match[2]])) {
+    const why = judgeCommand(inner, { cwd, home, now });
+    if (why) return why;
+  }
+  let here = cwd;
+  for (const { words: all } of commandsOf(noHereDocs(text))) {
+    const words = commandWords(all);
+    if (words[0] === 'cd' && words[1] && words[1] !== '-') { here = resolve(here, words[1].replace(/^~(?=\/|$)/, home)); continue; }
+    // A command line handed to a shell or to eval is read the same way.
+    const flag = words.findIndex((word, k) => k > 0 && /^-[A-Za-z]*c[A-Za-z]*$/.test(word));
+    const inner = ['sh', 'bash', 'zsh', 'dash', 'ksh'].includes(words[0]) && flag > 0 ? words[flag + 1] : words[0] === 'eval' ? words.slice(1).join(' ') : null;
+    if (inner) {
+      const why = judgeCommand(inner, { cwd: here, home, now });
+      if (why) return why;
+    }
+    if (words[0] === 'git') {
+      const why = judgeGit(words, here, home);
+      if (why) return why;
+    }
+    if (words[0] === 'gh') {
+      const why = judgeGh(words, { home, now, cwd: here });
+      if (why) return why;
+    }
+  }
+  return null;
+}
+
+// -------------------------------------------------------------------- git
+
+function judgeGit(words, cwd, home) {
+  let i = 1;
+  let dir = cwd;
+  while (i < words.length && words[i].startsWith('-')) {
+    if (words[i] === '-C') { dir = resolve(dir, String(words[i + 1] ?? '').replace(/^~(?=\/|$)/, home)); i += 2; continue; }
+    if (words[i] === '-c') { i += 2; continue; }
+    i += 1;
+  }
+  if (words[i] !== 'push') return null;
+  const args = words.slice(i + 1);
+  const spots = [];
+  let deleting = false;
+  for (let k = 0; k < args.length; k += 1) {
+    const arg = args[k];
+    if (/^\d*[<>]/.test(arg) || /^&>/.test(arg)) { if (/^\d*[<>]+&?$|^&>$/.test(arg)) k += 1; continue; }
+    if (arg === '--') { spots.push(...args.slice(k + 1)); break; }
+    if (/^--(force|force-with-lease|force-if-includes|mirror)(=|$)/.test(arg)) return `the merge door refuses a force push (${arg.split('=')[0]}). Merge the main branch into your branch, and push again.`;
+    if (/^--(all|branches)$/.test(arg)) return `the merge door refuses "git push ${arg}": it pushes the default branch too. Push one work branch.`;
+    if (arg === '--delete') { deleting = true; continue; }
+    if (/^--(repo|receive-pack|exec|push-option|signed)$/.test(arg) || arg === '-o') { k += 1; continue; }
+    if (arg.startsWith('--')) continue;
+    if (/^-[A-Za-z]+$/.test(arg)) {
+      if (arg.includes('f')) return 'the merge door refuses a force push (-f). Merge the main branch into your branch, and push again.';
+      if (arg.includes('d')) deleting = true;
+      continue;
+    }
+    spots.push(arg);
+  }
+  const git = gitFolder(dir);
+  const defaults = new Set([...DEFAULTS, ...(git ? remoteDefaults(git.common) : [])]);
+  const current = () => (git ? currentBranch(git.dir) : null);
+  const refs = spots.slice(1);
+  if (!refs.length) {
+    const branch = current();
+    if (!deleting && branch && defaults.has(branch)) return `the merge door refuses a push from ${branch}, the default branch. Make a work branch and open a pull request.`;
+    return null;
+  }
+  for (const ref of refs) {
+    if (ref.startsWith('+')) return `the merge door refuses a force push ("${ref}"). Merge the main branch into your branch, and push again.`;
+    const colon = ref.indexOf(':');
+    const source = colon >= 0 ? ref.slice(0, colon) : ref;
+    let target = colon >= 0 ? ref.slice(colon + 1) || source : ref;
+    if (target === 'HEAD' || target === '@') target = current() ?? '';
+    target = target.replace(/^refs\/heads\//, '');
+    if (!target || !defaults.has(target)) continue;
+    if (deleting || source === '') return `the merge door refuses a push that deletes ${target}, the default branch.`;
+    return `the merge door refuses a push to ${target}, the default branch. Push a work branch and open a pull request.`;
+  }
+  return null;
+}
+
+// The git folder of a work tree: { dir, common }. A linked work tree keeps
+// HEAD in its own folder and the remotes in the common one.
+export function gitFolder(start) {
+  for (let dir = start; ; dir = dirname(dir)) {
+    const dot = join(dir, '.git');
+    try {
+      if (statSync(dot).isDirectory()) return { dir: dot, common: dot };
+      const link = /^gitdir:\s*(.+)$/m.exec(readFileSync(dot, 'utf8'))?.[1]?.trim();
+      if (link) {
+        const own = isAbsolute(link) ? link : resolve(dir, link);
+        let common = own;
+        try { const shared = readFileSync(join(own, 'commondir'), 'utf8').trim(); common = isAbsolute(shared) ? shared : resolve(own, shared); } catch { /* not a linked work tree */ }
+        return { dir: own, common };
+      }
+    } catch { /* no .git here */ }
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+function currentBranch(gitDir) {
+  try { return /^ref:\s*refs\/heads\/(.+)$/m.exec(readFileSync(join(gitDir, 'HEAD'), 'utf8'))?.[1]?.trim() ?? null; } catch { return null; }
+}
+
+// The default branch names for one repo: main, master, and the remote HEAD of
+// the session's own copy when its origin is that repo.
+function defaultsFor(repo, cwd) {
+  const out = new Set(DEFAULTS);
+  const git = gitFolder(cwd);
+  if (git && String(originRepo(cwd) ?? '').toLowerCase() === String(repo).toLowerCase()) for (const name of remoteDefaults(git.common)) out.add(name);
+  return out;
+}
+
+// owner/name of the origin remote, from the git config, when it is on GitHub.
+function originRepo(cwd) {
+  const git = gitFolder(cwd);
+  if (!git) return null;
+  try {
+    const config = readFileSync(join(git.common, 'config'), 'utf8');
+    const block = /\[remote "origin"\]([^[]*)/.exec(config)?.[1] ?? '';
+    const url = /^\s*url\s*=\s*(.+)$/m.exec(block)?.[1]?.trim() ?? '';
+    return /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/.exec(url)?.[1] ?? null;
+  } catch { return null; }
+}
+
+function remoteDefaults(common) {
+  const out = [];
+  for (const remote of ['origin', 'upstream']) {
+    try {
+      const head = /^ref:\s*refs\/remotes\/[^/]+\/(.+)$/m.exec(readFileSync(join(common, 'refs', 'remotes', remote, 'HEAD'), 'utf8'))?.[1]?.trim();
+      if (head) out.push(head);
+    } catch { /* no such remote */ }
+  }
+  return out;
+}
+
+// --------------------------------------------------------------------- gh
+
+function judgeGh(words, { home, now, cwd }) {
+  const [, group, verb] = words;
+  if (group === 'api') {
+    let method = null;
+    let path = null;
+    let fields = false;
+    const values = [];
+    const rest = words.slice(2);
+    for (let k = 0; k < rest.length; k += 1) {
+      const arg = rest[k];
+      const [name, joined] = arg.startsWith('--') && arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, null];
+      const value = () => String(joined !== null ? joined : rest[++k] ?? '');
+      if (name === '-X' || name === '--method') { method = value().toUpperCase(); continue; }
+      if (/^-X[A-Za-z]+$/.test(name)) { method = name.slice(2).toUpperCase(); continue; }
+      if (['-f', '-F', '--field', '--raw-field', '--input'].includes(name)) { fields = true; values.push(value()); continue; }
+      if (['-H', '--header', '-q', '--jq', '-t', '--template', '--hostname', '--cache', '-p', '--preview'].includes(name)) { value(); continue; }
+      if (name.startsWith('-')) continue;
+      if (path === null) path = arg;
+    }
+    method = method ?? (fields ? 'POST' : 'GET');
+    path = String(path ?? '').split('?')[0];
+    if (path === 'graphql' || /\/graphql$/.test(path)) return GQL_MERGE.test(values.join(' ')) ? 'the merge door refuses a merge or a branch write through GraphQL. Merge with the GitHub merge tool or "gh pr merge", after "atlas gate ready" says READY.' : null;
+    if (method === 'GET') return null;
+    const newBranch = method === 'POST' && /(^|\/)git\/refs$/.test(path);
+    if (GH_MERGE_PATH.test(path) || (GH_REFS_PATH.test(path) && !newBranch)) return `the merge door refuses "gh api --method ${method} ${path}". Merge with the GitHub merge tool or "gh pr merge", after "atlas gate ready" says READY.`;
+    if (/\/contents\//.test(path)) {
+      const branch = values.map((each) => /^branch=(.+)$/.exec(each)?.[1]).find(Boolean);
+      if (!branch || defaultsFor(/^\/?repos\/([^/]+\/[^/]+)\//.exec(path)?.[1] ?? '', cwd).has(branch)) return 'the merge door refuses a file write through "gh api" to the default branch. Name a work branch with -f branch=<name>.';
+    }
+    return null;
+  }
+  if (group !== 'pr' || verb !== 'merge') return null;
+  const args = words.slice(3);
+  let repo = null;
+  let pr = null;
+  let sha = null;
+  let undo = false;
+  for (let k = 0; k < args.length; k += 1) {
+    const arg = args[k];
+    const [name, joined] = arg.startsWith('--') && arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, null];
+    const value = () => (joined !== null ? joined : args[++k]);
+    if (name === '--admin') return 'the merge door refuses "gh pr merge --admin": it skips the checks.';
+    if (name === '--disable-auto') { undo = true; continue; }
+    if (name === '-R' || name === '--repo') { repo = value(); continue; }
+    if (name === '--match-head-commit') { sha = value(); continue; }
+    if (['-b', '--body', '-F', '--body-file', '-t', '--subject', '-A', '--author-email'].includes(name)) { value(); continue; }
+    if (name.startsWith('-')) continue;
+    const url = /github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+)/.exec(arg);
+    if (url) { repo = repo ?? url[1]; pr = url[2]; continue; }
+    if (/^#?\d+$/.test(arg)) pr = arg.replace('#', '');
+  }
+  if (undo) return null;
+  repo = repo ?? originRepo(cwd);
+  if (!repo || !pr) return 'the merge door refuses "gh pr merge" without a pull request number, and a --repo <owner/name> or a GitHub origin. It cannot match the merge to a READY answer otherwise.';
+  repo = repo.replace(/^https?:\/\/github\.com\//, '').replace(/\.git$/, '');
+  return needReady({ repo, pr, sha, home, now, how: '--match-head-commit' });
+}
+
+// ------------------------------------------------------------------- main
+
+function main(input) {
+  if (process.env.ATLAS_HOOKS === 'off') return;
+  let call;
+  try { call = JSON.parse(input); } catch { return; }
+  let why;
+  try { why = judge(call); } catch (error) {
+    // A merge or push that the door cannot read is refused; anything else goes on.
+    if (!/merge|push|create_or_update_file|delete_file/.test(String(call?.tool_name ?? '') + JSON.stringify(call?.tool_input ?? {}))) return;
+    why = `the merge door could not read this call (${error.message}), so it refuses it.`;
+  }
+  if (!why) return;
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: `Atlas: ${why}` } }));
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const chunks = [];
+  process.stdin.on('data', (chunk) => chunks.push(chunk));
+  process.stdin.on('end', () => { main(Buffer.concat(chunks).toString('utf8')); process.exit(0); });
+}

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Loads the Atlas lead at the start of each session in a repo that runs Atlas.",
+  "description": "Loads the Atlas lead at the start of each session in a repo that runs Atlas, and keeps the merge door: no merge without a fresh READY, no push to the default branch, no force push.",
   "hooks": {
     "SessionStart": [
       {
@@ -11,6 +11,18 @@
           }
         ]
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit|mcp__.*(merge_pull_request|enable_pr_auto_merge|push_files|create_or_update_file|delete_file)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/door.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/lead.sh

@@ -1,5 +1,5 @@
 #!/bin/sh
-# The one hook Atlas ships. At the start of a session it prints the lead
+# The first hook Atlas ships. At the start of a session it prints the lead
 # skill, so a repo that runs Atlas gets the lead with no step from its people.
 #
 # Its limits are the reason the package may ship it:

package/package.json

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

package/skills/sdlc-task/SKILL.md

@@ -153,6 +153,11 @@ A lock is the owner's approval of a short design.
       the merge call, so a later push cannot slip in.
    4. Where the verb `apply` set the rulesets, the branch rule holds the
       merge. Turn on auto-merge there, and never press merge.
+   5. The merge door hook holds this step in the session. It refuses a
+      merge with no READY from the last ten minutes, or at another head.
+      It refuses a push to the main branch and a force push. It refuses the
+      auto-merge tool; `gh pr merge --auto --match-head-commit` names the
+      head. When it refuses, do what its reason says. Never work around it.
 
 ## pause
 

package/skills/upkeep/SKILL.md

@@ -94,8 +94,10 @@ If the tracker cannot be reached, skip this half and say so.
    "Upkeep <date>: <what changed>". The body lists each change on one line.
    It ends with "no item: the daily upkeep run".
 7. Wait for every check on the pull request. When all are green and the
-   diff changes only index lines and link targets, merge it with a merge
-   commit. Otherwise leave it open and say why in the report.
+   diff changes only index lines and link targets, run `atlas gate` with
+   the verb `ready`, `--repo` and `--pr`. On READY, merge it with a merge
+   commit at the head SHA that ready read. The merge door hook refuses any
+   other merge. Otherwise leave it open and say why in the report.
 
 ## The run line