@arjunkhera/atlas 0.2.2 → 0.3.0

package/door/lib/helpers.mjs

@@ -1,139 +0,0 @@
-// 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/onboarding.mjs

@@ -1,130 +0,0 @@
-// `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;
-}