@arjunkhera/atlas 0.0.0 → 0.2.1

package/door/lib/helpers.mjs

@@ -0,0 +1,139 @@
+// The five helpers, and the entry verb that routes to them.
+//
+// Milestone M2, slice L2 stage one. Authority:
+// Atlas amendment A1.6, section 5, the L2 stage
+// one paragraph; the Atlas architecture record, section 5.1.
+//
+// One helper per class of file. You never pick one. You say what changed, and
+// the entry verb routes it. "We now deploy prod on Fly" reaches Facts, which
+// edits atlas/deploy.yaml, and Procedures, which updates the deploy skill. One
+// request, two helpers, one pull request.
+//
+// What a helper does here: it says which files it owns, it refuses a change to
+// a file it does not own, and it carries the change into one pull request with
+// the fixed label and per-change provenance. It does not draft. An agent in a
+// session drafts, because drafting needs a model and a read of the repository.
+// The tooling helper is the exception: both the files it owns are written from
+// the package, so it needs no model at all.
+import { posix } from 'node:path';
+
+// R13, from the M2 design study's review panel: agent-invoked helper pull
+// requests carried no provenance. Every change now names where it came from,
+// and the set is closed.
+export const PROVENANCE_SOURCES = Object.freeze(['owner words', 'repo read', 'task input']);
+
+// The one label every helper pull request carries. A person filters on it, and
+// slice L4's merge actor reads it.
+export const HELPER_LABEL = 'atlas-helper';
+
+const under = (...prefixes) => (path) => prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+const isOneOf = (...paths) => (path) => paths.includes(path);
+
+export const HELPERS = Object.freeze([
+  {
+    id: 'entry-map',
+    file: 1,
+    title: 'Entry map',
+    owns: isOneOf('CLAUDE.md', 'AGENTS.md'),
+    ownsText: 'CLAUDE.md, AGENTS.md',
+    forWhat: 'Keeps the front door true: what the repo is, how to build it, where things are.',
+    youMightSay: 'the modules moved, refresh the map',
+    words: ['entry map', 'claude.md', 'agents.md', 'front door', 'layout', 'module', 'modules', 'readme', 'structure', 'moved'],
+  },
+  {
+    id: 'rules',
+    file: 2,
+    title: 'Path rules',
+    owns: under('.claude/rules'),
+    ownsText: '.claude/rules/*.md',
+    forWhat: 'Records a constraint that holds under one path only.',
+    youMightSay: 'migrations are append-only under migrations/',
+    words: ['rule', 'rules', 'constraint', 'never', 'append-only', 'forbidden', 'must not', 'policy'],
+  },
+  {
+    id: 'procedures',
+    file: 3,
+    title: 'Procedures',
+    owns: (path) => path.startsWith('.claude/skills/') && path.endsWith('/SKILL.md'),
+    ownsText: '.claude/skills/<name>/SKILL.md',
+    forWhat: 'Keeps the how-to for running, testing, deploying and releasing.',
+    youMightSay: 'we changed how we deploy',
+    words: ['skill', 'procedure', 'how to', 'run locally', 'test', 'tests', 'deploy', 'release', 'ship', 'runbook'],
+  },
+  {
+    id: 'facts',
+    file: 4,
+    title: 'Repo facts',
+    owns: (path) => path === 'atlas.yaml' || under('atlas')(path),
+    ownsText: 'atlas.yaml, atlas/',
+    forWhat: 'Holds where it runs, where the logs are, and every credential by name.',
+    youMightSay: 'add a staging environment on Fly',
+    words: ['fact', 'facts', 'atlas.yaml', 'environment', 'staging', 'prod', 'logs', 'metrics', 'credential', 'credentials', 'dependency', 'dependencies', 'kind', 'deploy target', 'fly', 'region'],
+  },
+  {
+    id: 'tooling',
+    file: 7,
+    title: 'Tooling',
+    owns: (path) => path === '.github/atlas/check.mjs' || path === '.github/workflows/atlas-check.yml',
+    ownsText: '.github/atlas/check.mjs, .github/workflows/atlas-check.yml',
+    forWhat: 'Keeps the automatic checks this repo runs.',
+    youMightSay: 'refresh the Atlas check',
+    words: ['check', 'workflow', 'ci', 'lint', 'linter', 'action', 'tooling', 'refresh the check', 'atlas check'],
+  },
+]);
+
+export const helperById = (id) => HELPERS.find((helper) => helper.id === id) ?? null;
+
+// Which helper owns a path. null means no helper owns it, and no helper may
+// write it.
+export function ownerOf(path) {
+  const clean = posix.normalize(String(path ?? '')).replace(/^\.\//, '');
+  return HELPERS.find((helper) => helper.owns(clean)) ?? null;
+}
+
+// The entry verb's routing. You say what changed; this says which helpers it
+// reaches, in file order. An empty list is an honest answer: it means the
+// sentence names nothing any helper owns, and the caller should say more.
+export function route(say) {
+  const text = String(say ?? '').toLowerCase();
+  if (!text.trim()) return [];
+  return HELPERS.filter((helper) => helper.words.some((word) => text.includes(word)));
+}
+
+// First setup is the same verb. It runs all five, in file order. There is no
+// separate first-run path to maintain.
+export const setupOrder = () => [...HELPERS];
+
+export class HelperError extends Error {}
+
+// Every change a helper carries, checked before anything is written.
+//
+// Two rules, and both are about who may write what. A helper writes only the
+// files it owns, so one request cannot quietly rewrite another class of file.
+// Every change names its source, so a reader of the pull request can tell an
+// owner decision from a guess.
+export function checkChanges(helperId, changes) {
+  const helper = helperById(helperId);
+  if (!helper) throw new HelperError(`there is no helper "${helperId}"; the helpers are ${HELPERS.map((one) => one.id).join(', ')}`);
+  if (!Array.isArray(changes) || !changes.length) throw new HelperError('a helper needs at least one change to carry');
+  for (const change of changes) {
+    const path = String(change?.path ?? '');
+    if (!path) throw new HelperError('a change has no path');
+    if (path.startsWith('/') || path.includes('..')) throw new HelperError(`"${path}" leaves the repo; a helper writes inside one repo only`);
+    if (!helper.owns(path)) {
+      const other = ownerOf(path);
+      throw new HelperError(other
+        ? `the ${helper.id} helper does not own "${path}"; the ${other.id} helper does. Route the change there.`
+        : `no helper owns "${path}"; the five helpers own ${HELPERS.map((one) => one.ownsText).join('; ')}`);
+    }
+    if (typeof change.contents !== 'string') throw new HelperError(`the change to "${path}" carries no contents`);
+    const source = change?.provenance?.source;
+    if (!PROVENANCE_SOURCES.includes(source)) {
+      throw new HelperError(`the change to "${path}" names no source; every change names one of ${PROVENANCE_SOURCES.join(', ')} (review finding R13)`);
+    }
+    if (!String(change?.provenance?.detail ?? '').trim()) {
+      throw new HelperError(`the change to "${path}" names the source "${source}" and says nothing about it; give the words, the file read, or the task`);
+    }
+  }
+  return helper;
+}

package/door/lib/install.mjs

@@ -0,0 +1,260 @@
+// atlas install, atlas upgrade, atlas doctor: Atlas on one Mac.
+//
+// Row F11, amendment A1.9; the design is "Install and upgrade on the Mac" in
+// the Atlas F11 study.
+//
+// The catalog is one folder on the Mac, ~/.atlas/catalog. It holds one entry
+// that pins an exact npm version, so nothing moves Atlas to another version
+// without `atlas upgrade`. The installer writes that one file and asks Claude
+// Code to add the catalog and install the plugin. It writes no settings file.
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+export const CATALOG_NAME = 'atlas';
+export const PLUGIN_ID = 'atlas@atlas';
+export const DEV_PLUGIN_ID = 'atlas@atlas-dev';
+const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
+
+const packageJson = (packageRoot) => JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+export function repoOf(packageRoot) {
+  const url = packageJson(packageRoot).repository?.url ?? '';
+  const found = /github\.com[/:]([^/]+\/[^/.]+)/.exec(url)?.[1];
+  if (!found) throw new Error('package.json names no GitHub repository');
+  return found;
+}
+
+export const catalogDir = (env) => join(env.HOME, '.atlas', 'catalog');
+export const catalogFile = (env) => join(catalogDir(env), '.claude-plugin', 'marketplace.json');
+
+// The one file the installer writes. `local` puts a copy of the package inside
+// the catalog instead of naming npm; CI and a development Mac use it.
+export function catalogFor({ name, version, local = false }) {
+  if (!local && !EXACT_VERSION.test(version)) throw new Error(`"${version}" is not an exact version`);
+  return {
+    name: CATALOG_NAME,
+    owner: { name: 'Atlas' },
+    description: 'Atlas on this Mac. atlas upgrade moves the pin; nothing else does.',
+    plugins: [{
+      name: 'atlas',
+      description: 'The delivery lifecycle, its crews and the Atlas tools.',
+      source: local ? './atlas' : { source: 'npm', package: name, version },
+    }],
+  };
+}
+
+function defaultExec(command, args, { input } = {}) {
+  return execFileSync(command, args, { encoding: 'utf8', input, maxBuffer: 64 * 1024 * 1024, timeout: 600_000, stdio: ['pipe', 'pipe', 'pipe'] });
+}
+
+async function defaultAsk(question) {
+  if (!process.stdin.isTTY) return false;
+  const reader = createInterface({ input: process.stdin, output: process.stdout });
+  try { return /^y(es)?$/i.test((await reader.question(`${question} [y/N] `)).trim()); } finally { reader.close(); }
+}
+
+function claudePlugins(exec) {
+  try { return JSON.parse(exec('claude', ['plugin', 'list', '--json'])); } catch { return null; }
+}
+const pluginRows = (listed) => (Array.isArray(listed) ? listed : listed?.plugins ?? listed?.installed ?? []);
+const findPlugin = (listed, id) => pluginRows(listed).find((row) => row.id === id || `${row.name}@${row.marketplace}` === id) ?? null;
+
+// ---------------------------------------------------------------- install
+
+export async function install({ packageRoot, options = {}, line = console.log, env = process.env, exec = defaultExec, ask = defaultAsk }) {
+  const { name, version } = packageJson(packageRoot);
+  const local = Boolean(options.local);
+  const from = options.from && options.from !== true ? String(options.from) : null;
+  const catalog = catalogFor({ name, version, local });
+  const file = catalogFile(env);
+  const before = existsSync(file) ? readFileSync(file, 'utf8') : null;
+  const after = `${JSON.stringify(catalog, null, 2)}\n`;
+
+  line(`Install Atlas ${version} for every folder on this Mac.`);
+  line('');
+  line('What this does, in order:');
+  const steps = [
+    options['skip-global'] ? null : `npm install -g --ignore-scripts ${from ?? `${name}@${version}`}   (puts "atlas" on your terminal path)`,
+    `write ${file}   (${before === null ? 'new file' : before === after ? 'unchanged' : 'changed'}; it pins ${local ? 'a local copy' : `exactly ${version}`})`,
+    `claude plugin marketplace add ${catalogDir(env)}`,
+    `claude plugin install ${PLUGIN_ID} --scope user`,
+    'atlas doctor',
+  ].filter(Boolean);
+  steps.forEach((step, index) => line(`  ${index + 1}. ${step}`));
+  line('');
+  line('Claude Code itself then writes two keys into ~/.claude/settings.json, and nothing else:');
+  line(`  extraKnownMarketplaces.${CATALOG_NAME}   (the catalog folder)`);
+  line(`  enabledPlugins["${PLUGIN_ID}"] = true`);
+  line('This command writes no settings file of its own.');
+  if (before !== null && before !== after) { line(''); line('The catalog file changes from:'); line(before); line('to:'); line(after); }
+  if (!options.yes && !(await ask('Go ahead?'))) { line('Nothing was changed.'); return 1; }
+
+  if (!options['skip-global']) exec('npm', ['install', '-g', '--ignore-scripts', from ?? `${name}@${version}`]);
+  mkdirSync(join(catalogDir(env), '.claude-plugin'), { recursive: true });
+  if (local) {
+    const target = join(catalogDir(env), 'atlas');
+    rmSync(target, { recursive: true, force: true });
+    // Filter on the path inside the package: a global install itself sits under
+    // node_modules/, so a filter on the full path would copy nothing.
+    cpSync(packageRoot, target, { recursive: true, filter: (path) => !/(^|\/)(node_modules|\.claude)(\/|$)/.test(relative(packageRoot, path)) });
+  }
+  writeFileSync(file, after);
+  const known = (() => { try { return JSON.parse(exec('claude', ['plugin', 'marketplace', 'list', '--json'])); } catch { return []; } })();
+  const hasCatalog = (Array.isArray(known) ? known : known?.marketplaces ?? []).some((row) => row.name === CATALOG_NAME);
+  exec('claude', hasCatalog ? ['plugin', 'marketplace', 'update', CATALOG_NAME] : ['plugin', 'marketplace', 'add', catalogDir(env)]);
+  const installArgs = ['plugin', 'install', PLUGIN_ID, '--scope', 'user'];
+  exec('claude', installArgs);
+  line('');
+  line('Installed. Open Claude Code, run /plugin, choose atlas, and set the Engram connection:');
+  line('  https://<your Engram host> <your Engram key>');
+  line('');
+  return doctor({ packageRoot, options, line, env, exec });
+}
+
+// ---------------------------------------------------------------- upgrade
+
+// A git blob id, as GitHub's tree API reports it.
+export const blobSha = (bytes) => createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+export const sha512Integrity = (bytes) => `sha512-${createHash('sha512').update(bytes).digest('base64')}`;
+
+function filesUnder(root) {
+  const out = new Map();
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full);
+      else out.set(relative(root, full).split('\\').join('/'), readFileSync(full));
+    }
+  };
+  walk(root);
+  return out;
+}
+
+// Is `sha` a commit of the master branch itself? A run's branch name is not
+// enough: a tag named "master" gives a run the same name.
+export function onMaster(gh, repo, sha) {
+  const compare = gh(['api', '--method', 'GET', `repos/${repo}/compare/${sha}...refs/heads/master`]);
+  return ['ahead', 'identical'].includes(compare.status);
+}
+
+// The master run of release.yml that built this version, or null.
+export function findReleaseRun({ gh, repo, version }) {
+  const runs = gh(['api', '--method', 'GET', `repos/${repo}/actions/workflows/release.yml/runs?event=push&status=success&per_page=100`]).workflow_runs ?? [];
+  for (const run of runs) {
+    if (!/^[0-9a-f]{40}$/.test(run.head_sha ?? '')) continue;
+    let named;
+    try {
+      const file = gh(['api', '--method', 'GET', `repos/${repo}/contents/packages/atlas/package.json?ref=${run.head_sha}`]);
+      named = JSON.parse(Buffer.from(file.content, 'base64').toString('utf8')).version;
+    } catch { continue; }
+    if (named !== version) continue;
+    if (!onMaster(gh, repo, run.head_sha)) continue;
+    return run;
+  }
+  return null;
+}
+
+// Every file of the tarball must be the file at that commit, and every file of
+// packages/atlas at that commit must be in the tarball.
+export function matchTree({ tree, files }) {
+  const wanted = new Map((tree ?? []).filter((row) => row.type === 'blob' && row.path.startsWith('packages/atlas/')).map((row) => [row.path.slice('packages/atlas/'.length), row.sha]));
+  const problems = [];
+  for (const [path, bytes] of files) {
+    if (!wanted.has(path)) problems.push(`${path} is in the tarball and not in the commit`);
+    else if (wanted.get(path) !== blobSha(bytes)) problems.push(`${path} differs from the commit`);
+  }
+  for (const path of wanted.keys()) if (!files.has(path)) problems.push(`${path} is in the commit and not in the tarball`);
+  return problems;
+}
+
+export async function upgrade({ packageRoot, options = {}, line = console.log, env = process.env, exec = defaultExec, ask = defaultAsk }) {
+  const { name, version: installed } = packageJson(packageRoot);
+  const repo = repoOf(packageRoot);
+  const gh = (args) => JSON.parse(exec('gh', args));
+  const target = options.version && options.version !== true ? String(options.version) : exec('npm', ['view', name, 'version']).trim();
+  if (!EXACT_VERSION.test(target)) throw new Error(`npm answered "${target}", which is not a version`);
+  if (target === installed) { line(`Atlas ${installed} is the newest release. Nothing to do.`); return 0; }
+  const integrity = exec('npm', ['view', `${name}@${target}`, 'dist.integrity']).trim();
+
+  line(`Atlas ${installed} → ${target}`);
+  const run = findReleaseRun({ gh, repo, version: target });
+  if (!run) { line(`Refused: no successful release run on a commit of master built ${target}. It may have been published from a branch.`); return 1; }
+  line(`  built by release run ${run.id}, on master commit ${run.head_sha.slice(0, 12)}`);
+
+  const work = mkdtempSync(join(tmpdir(), 'atlas-upgrade-'));
+  try {
+    exec('npm', ['pack', `${name}@${target}`, '--pack-destination', work]);
+    const tarball = readdirSync(work).find((entry) => entry.endsWith('.tgz'));
+    if (!tarball) throw new Error('npm pack wrote no tarball');
+    const bytes = readFileSync(join(work, tarball));
+    if (sha512Integrity(bytes) !== integrity) { line('Refused: the tarball does not match the integrity npm records.'); return 1; }
+    const unpacked = join(work, 'unpacked');
+    mkdirSync(unpacked);
+    exec('tar', ['-xzf', join(work, tarball), '-C', unpacked]);
+    const files = filesUnder(join(unpacked, 'package'));
+    const tree = gh(['api', '--method', 'GET', `repos/${repo}/git/trees/${run.head_sha}?recursive=1`]).tree;
+    const problems = matchTree({ tree, files });
+    if (problems.length) {
+      line('Refused: the tarball is not the commit that run built.');
+      for (const problem of problems.slice(0, 20)) line(`  ${problem}`);
+      return 1;
+    }
+    line(`  every one of ${files.size} files matches that commit`);
+
+    const current = existsSync(packageRoot) ? filesUnder(packageRoot) : new Map();
+    const watched = /^(\.mcp\.json|\.claude-plugin\/|bin\/|door\/|work\/)/;
+    const changed = [...new Set([...files.keys(), ...current.keys()])].filter((path) => watched.test(path) && Buffer.compare(files.get(path) ?? Buffer.alloc(0), current.get(path) ?? Buffer.alloc(0)) !== 0).sort();
+    line('');
+    line(changed.length ? `Changed in the parts that run code or hold the key (${changed.length}):` : 'No change in the parts that run code or hold the key.');
+    for (const path of changed) line(`  ${current.has(path) ? (files.has(path) ? 'changed' : 'removed') : 'added  '}  ${path}`);
+    line('');
+    if (!options.yes && !(await ask(`Install Atlas ${target}?`))) { line('Nothing was changed.'); return 1; }
+
+    exec('npm', ['install', '-g', '--ignore-scripts', join(work, tarball)]);
+    writeFileSync(catalogFile(env), `${JSON.stringify(catalogFor({ name, version: target }), null, 2)}\n`);
+    exec('claude', ['plugin', 'marketplace', 'update', CATALOG_NAME]);
+    exec('claude', ['plugin', 'update', PLUGIN_ID]);
+    line(`Installed Atlas ${target}. Restart Claude Code sessions to load it.`);
+    return 0;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------- doctor
+
+export function doctor({ packageRoot, options = {}, line = console.log, env = process.env, exec = defaultExec }) {
+  const { version } = packageJson(packageRoot);
+  const rows = [];
+  const check = (name, pass, detail) => rows.push({ name, pass, detail });
+
+  const listed = claudePlugins(exec);
+  const plugin = findPlugin(listed, PLUGIN_ID);
+  const dev = findPlugin(listed, DEV_PLUGIN_ID);
+  check('plugin', Boolean(plugin), plugin ? `${PLUGIN_ID} ${plugin.version ?? '?'} is installed, scope ${plugin.scope ?? '?'}` : `${PLUGIN_ID} is not installed. Run "atlas install".`);
+
+  let pinned = null;
+  try { pinned = JSON.parse(readFileSync(catalogFile(env), 'utf8')).plugins?.[0]?.source ?? null; } catch { /* missing */ }
+  const local = typeof pinned === 'string';
+  check('catalog', local || (pinned?.version === version && EXACT_VERSION.test(pinned.version)),
+    local ? 'the catalog holds a local copy' : pinned ? `the catalog pins exactly ${pinned.version}${pinned.version === version ? '' : `, and this command is ${version}`}` : `${catalogFile(env)} is missing. Run "atlas install".`);
+
+  // Only where the dev copy is on, which is the Atlas repo, may the two differ.
+  if (plugin && !dev?.enabled) {
+    check('one version', !plugin.version || plugin.version === version, `the plugin is ${plugin.version ?? '?'} and the terminal command is ${version}`);
+  }
+
+  let health = null;
+  try { health = JSON.parse(readFileSync(join(env.HOME, '.atlas', 'health.json'), 'utf8')); } catch { /* never started */ }
+  check('tools server', Boolean(health), health ? `last started ${health.started_at}, Atlas ${health.package_version}` : 'the Atlas tools server has not started yet. Open a Claude Code session, then run "atlas doctor" again.');
+  if (health) {
+    check('engram', health.engram === 'answered', health.engram === 'answered' ? `Engram answered; the key expires ${health.connection_expires}` : `Engram: ${health.engram}`);
+    check('gh', Boolean(health.gh), health.gh ? `the server finds gh at ${health.gh}` : 'the tools server cannot find gh on its path. Install gh, or put it where the desktop app looks: /usr/local/bin.');
+  }
+
+  for (const row of rows) line(`${row.pass ? 'PASS' : 'FAIL'}  ${row.name.padEnd(12)} ${row.detail}`);
+  return rows.every((row) => row.pass) ? 0 : 1;
+}

package/door/lib/kind-drift.mjs

@@ -0,0 +1,76 @@
+// The facts helper's kind drift report.
+//
+// Milestone M2, slice L2 stage one: "The facts helper compares the `kind` in
+// `atlas.yaml` with the `kind` on the repo record and reports drift."
+//
+// The kind decides which of the seven files a repository needs, so the two
+// copies disagreeing is not a detail. A repo record that says `service` while
+// atlas.yaml says `library` means four required parts read "not applicable" in
+// CI and "required" everywhere else.
+//
+// Which of the two is the source is open question O-9, and the owner settles it
+// before slice L2 ends. This report is neutral on that: it names both values
+// and says they differ. It never picks a winner, and it never writes.
+//
+// Where the record comes from. Reading it live needs the Atlas work verbs and
+// an Engram owner token, which CI does not have and this module does not hold.
+// So the record's kind is an input. Pass one repo's kind, or the JSON the
+// `registry_list` verb returns.
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseYaml, SPECS } from '../../shape/check.mjs';
+
+export const KINDS = Object.freeze(['service', 'library', 'schema']);
+
+// The kind a repository's own file declares, with the repo id beside it.
+export function fileKind(root) {
+  const path = join(root, 'atlas.yaml');
+  if (!existsSync(path)) return { kind: null, repo: null, error: 'atlas.yaml does not exist' };
+  try {
+    const facts = parseYaml(readFileSync(path, 'utf8'));
+    return { kind: facts?.kind ?? null, repo: facts?.repo ?? null, spec: facts?.spec ?? null, error: null };
+  } catch (error) {
+    // The parse error names a line and a column and never the content. That is
+    // the rule the whole check follows (amendment A1.6, section 4.9).
+    return { kind: null, repo: null, error: `atlas.yaml cannot be read: ${error.message}` };
+  }
+}
+
+// One repository, one verdict.
+export function driftOne({ root, recordKind = null, recordRepo = null }) {
+  const file = fileKind(root);
+  const known = (kind) => kind === null || KINDS.includes(kind);
+  const row = {
+    root,
+    repo: file.repo ?? recordRepo ?? null,
+    file_kind: file.kind,
+    record_kind: recordKind,
+    spec: file.spec ?? null,
+    state: 'unknown',
+    why: '',
+  };
+  if (file.error) { row.state = 'unreadable'; row.why = file.error; return row; }
+  if (!known(file.kind)) { row.state = 'unreadable'; row.why = `atlas.yaml names kind "${file.kind}"; a kind is one of ${KINDS.join(', ')}`; return row; }
+  if (recordKind === null) { row.state = 'unknown'; row.why = 'no repo record kind was given, so there is nothing to compare with. Read it with the registry_list verb and pass it in.'; return row; }
+  if (!known(recordKind)) { row.state = 'unreadable'; row.why = `the repo record names kind "${recordKind}"; a kind is one of ${KINDS.join(', ')}`; return row; }
+  if (file.kind === null) { row.state = 'drift'; row.why = `the repo record says "${recordKind}" and atlas.yaml names no kind at all, so CI cannot tell which files this repo needs`; return row; }
+  if (file.kind === recordKind) { row.state = 'agree'; row.why = `both say "${file.kind}"`; return row; }
+  row.state = 'drift';
+  row.why = `atlas.yaml says "${file.kind}" and the repo record says "${recordKind}". The kind decides which parts are required, so the check in CI and the work verbs are scoring two different repos. Open question O-9 says which one is the source.`;
+  return row;
+}
+
+// The registry the `registry_list` verb returns, as { repoId: kind }.
+export function kindsFromRegistry(registry) {
+  const out = {};
+  for (const product of registry?.products ?? []) {
+    for (const repo of product?.repos ?? []) if (repo?.registry_id) out[repo.registry_id] = repo.kind ?? null;
+  }
+  for (const repo of registry?.repos ?? []) if (repo?.registry_id) out[repo.registry_id] = repo.kind ?? null;
+  return out;
+}
+
+export function drift(rows) {
+  const out = rows.map(driftOne);
+  return { rows: out, drifting: out.filter((row) => row.state === 'drift').length, specs_read: Object.keys(SPECS).map(Number) };
+}

package/door/lib/onboarding.mjs

@@ -0,0 +1,130 @@
+// `atlas test onboarding`: the answer key, and the fixed script that compares.
+//
+// Milestone M2, slice L2 stage one, done line 5: "The fresh-agent test scores
+// 6 of 6 under the isolation rule."
+//
+// Why this exists. The M2 criterion said a fresh agent "completes the six-step
+// task list from the files alone, scored 6 of 6 by the answer key", and no
+// slice built the key or the scorer. Six of six was therefore a self-grade
+// (panel finding P4). This is the key, and this is the scorer.
+//
+// The scorer runs OUTSIDE the isolated session. The isolated session has the
+// Atlas package off, so it cannot score itself even if it wanted to. It writes
+// its six answers to a file; this reads that file.
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseYaml, secretPatterns } from '../../shape/check.mjs';
+
+
+// The isolation rule, in the words of closure R3. The scorer prints it, so the
+// person who runs the test sets the session up the same way every time.
+export const ISOLATION = Object.freeze([
+  'no memory directory',
+  'no global instructions',
+  'the Engram MCP disconnected',
+  'the Atlas package off',
+  'the repo at HEAD',
+]);
+
+// The answer key is read from a path. It never ships in the package and never
+// sits in the repository under test, because the agent under test must not be
+// able to read it (amendment A1.9, the L2 stage one clause).
+export function loadKey(path) {
+  if (!path || path === true) throw new Error('give the answer key with --key <path>. Keys stay outside the package and outside the repo under test.');
+  const full = resolve(String(path));
+  if (!existsSync(full)) throw new Error(`there is no answer key at ${full}`);
+  const key = parseYaml(readFileSync(full, 'utf8'));
+  if (!Array.isArray(key?.tasks) || !key.tasks.length) throw new Error(`${full} carries no tasks`);
+  return { ...key, path: full };
+}
+
+// The task list as the isolated session sees it: the questions, and nothing
+// else. No sources, no expected strings.
+export function questions(key) {
+  return key.tasks.map((task) => ({ id: task.id, number: task.number, ask: task.ask }));
+}
+
+const normalise = (text) => String(text ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
+
+// A phrase must appear as a whole word, not inside another one. Plain substring
+// matching passed "the dependencies file is nonexistent" for the phrase "none",
+// because "none" sits inside "nonexistent" (acceptance review of batch 16,
+// finding S2-5).
+//
+// What this still cannot do: it compares text, not meaning. "do not run
+// scripts/stack.mjs" carries the right words in the wrong order and passes.
+// The frozen text asks for "a fixed script that compares", so that limit is the
+// design, and it is written down here rather than left to be discovered.
+const says = (said, phrase) => {
+  const wanted = normalise(phrase);
+  if (!wanted) return false;
+  // The boundary is a letter, a digit or an underscore. Dots, slashes, commas
+  // and hyphens are boundaries, so "atlas/deploy.yaml." at the end of a
+  // sentence still matches, and "none" inside "nonexistent" still does not.
+  const edge = '[^a-z0-9_]';
+  return new RegExp(`(?:^|${edge})${wanted.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:$|${edge})`).test(said);
+};
+
+// One answer against one task.
+export function scoreTask(task, answer, patterns) {
+  const said = normalise(answer);
+  if (!said) return { id: task.id, number: task.number, pass: false, source: task.source, missing: task.must_say ?? [], why: 'no answer was given' };
+
+  // An answer that carries a credential value fails, whatever else it says.
+  // The file it read holds names only, so a value can only have come from
+  // somewhere it should not have been read from.
+  for (const pattern of patterns) {
+    if (pattern.test(String(answer ?? ''))) {
+      return { id: task.id, number: task.number, pass: false, source: task.source, missing: [], why: 'the answer holds something that looks like a credential value; these files carry names only' };
+    }
+  }
+
+  // The answer must cite a file. The test is whether the seven files answer on
+  // their own, so an answer that names no file proves nothing about them
+  // (acceptance review of batch 16, finding S2-5).
+  const cites = (task.cites ?? [task.source]).some((path) => says(said, path));
+  if (!cites) {
+    return { id: task.id, number: task.number, pass: false, source: task.source, missing: [task.source], why: `the answer names no source file; it should name ${task.source}` };
+  }
+
+  const anyOf = task.accept_any_of ?? [];
+  if (anyOf.length && anyOf.some((phrase) => says(said, phrase))) {
+    return { id: task.id, number: task.number, pass: true, source: task.source, missing: [], why: `the answer says what ${task.source} says, and names it` };
+  }
+  const missing = (task.must_say ?? []).filter((phrase) => !says(said, phrase));
+  return {
+    id: task.id,
+    number: task.number,
+    pass: !missing.length,
+    source: task.source,
+    missing,
+    why: missing.length ? `the answer does not name ${missing.join(', ')}; the file that says it is ${task.source}` : `the answer names what ${task.source} says, and names the file`,
+  };
+}
+
+// The whole run. `answers` is a map of task id to the answer text the isolated
+// session wrote.
+export function score(key, answers, { patterns = secretPatterns() } = {}) {
+  const rows = key.tasks.map((task) => scoreTask(task, answers?.[task.id] ?? answers?.[String(task.number)] ?? null, patterns));
+  const passed = rows.filter((row) => row.pass).length;
+  return {
+    repo: key.repo,
+    key: key.path,
+    isolation: ISOLATION,
+    rows,
+    passed,
+    of: key.tasks.length,
+    pass: passed >= (key.pass ?? key.tasks.length),
+  };
+}
+
+// The answers file the isolated session writes. YAML or JSON, one entry per
+// task id. Anything the key does not name is ignored, and a task with no entry
+// scores zero.
+export function readAnswers(path) {
+  const text = readFileSync(path, 'utf8');
+  const data = text.trimStart().startsWith('{') ? JSON.parse(text) : parseYaml(text);
+  const rows = data?.answers ?? data;
+  if (!rows || typeof rows !== 'object' || Array.isArray(rows)) throw new Error(`${path} is not a map of task id to answer`);
+  return rows;
+}