@arjunkhera/atlas 0.2.2 → 0.3.0

package/door/lib/pull-request.mjs

@@ -1,70 +1,74 @@
-// One helper change set becomes one pull request, with the fixed label and
-// per-change provenance.
+// The tooling change set becomes one pull request, with the fixed label and a
+// source for each change.
 //
-// Milestone M2, slice L2 stage one. The frozen sentence: "Helper pull requests
-// carry the fixed label and per-change provenance." The rule behind it is R13
-// of the M2 design study's review panel.
+// Stage 1 of the target design retired the five helpers and their phrase
+// router (decided 28 September: code that guesses meaning retires). The
+// tooling writer stays, because it is exact work: it copies two files from
+// the package. The onboarding skill of stage 2 names it; until then the lead
+// skill does.
 //
 // The body is built by a pure function, so a test reads it without GitHub. The
 // git and GitHub calls sit below it, in one place.
 import { execFileSync } from 'node:child_process';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { checkChanges, HELPER_LABEL, PROVENANCE_SOURCES } from './helpers.mjs';
+import { dirname, join, posix } from 'node:path';
+import { CHECK_PATH, WORKFLOW_PATH } from '../../shape/check.mjs';
 
-export { HELPER_LABEL, PROVENANCE_SOURCES };
+// Every change 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 tooling pull request carries. A person filters on it.
+export const TOOLING_LABEL = 'atlas-helper';
+
+// The only two files the tooling writer may write.
+export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH]);
+
+export class ChangeError extends Error {}
 
 // A backtick breaks a table cell the same way a pipe does, and a provenance
-// line often carries one. Both are escaped (acceptance review of slice B2).
+// line often carries one. Both are escaped.
 const escapeCell = (text) => String(text ?? '').replaceAll('|', '\\|').replaceAll('`', '\\`').replaceAll('\n', ' ').trim();
 
-// One request may reach two helpers. "We now deploy prod on Fly" reaches Facts
-// and Procedures. It is still ONE pull request: design page D2's rule, carried
-// here (architecture section 5.1, rule 1).
-export function checkAll(groups) {
-  if (!Array.isArray(groups) || !groups.length) throw new Error('a pull request needs at least one helper group');
-  const seen = new Map();
-  for (const group of groups) {
-    const helper = checkChanges(group.helperId, group.changes);
-    if (seen.has(helper.id)) throw new Error(`the ${helper.id} helper appears twice; put its changes in one group`);
-    seen.set(helper.id, { helper, changes: group.changes });
+// Every change, checked before anything is written. The writer writes only its
+// two files, and every change names its source.
+export function checkChanges(changes) {
+  if (!Array.isArray(changes) || !changes.length) throw new ChangeError('a tooling pull request needs at least one change');
+  for (const change of changes) {
+    const path = posix.normalize(String(change?.path ?? '')).replace(/^\.\//, '');
+    if (!path || path === '.') throw new ChangeError('a change has no path');
+    if (!TOOLING_PATHS.includes(path)) throw new ChangeError(`the tooling writer writes only ${TOOLING_PATHS.join(' and ')}; it refuses "${path}"`);
+    if (typeof change.contents !== 'string') throw new ChangeError(`the change to "${path}" carries no contents`);
+    const source = change?.provenance?.source;
+    if (!PROVENANCE_SOURCES.includes(source)) throw new ChangeError(`the change to "${path}" names no source; every change names one of ${PROVENANCE_SOURCES.join(', ')}`);
+    if (!String(change?.provenance?.detail ?? '').trim()) throw new ChangeError(`the change to "${path}" names the source "${source}" and says nothing about it`);
   }
-  return [...seen.values()].sort((a, b) => a.helper.file - b.helper.file);
+  return changes;
 }
 
 // The pull request body. Every change is one row, and every row names where the
-// change came from. A reader can tell an owner decision from a guess without
-// opening the diff.
-export function provenanceBody({ helper, helpers, why, changes, groups, repo = null }) {
-  const parts = groups ?? [{ helper, changes }];
-  const named = (helpers ?? parts.map((group) => group.helper));
+// change came from.
+export function provenanceBody({ why, changes, repo = null }) {
   const lines = [
-    named.length === 1
-      ? `The \`${named[0].title}\` helper wrote this. It owns ${named[0].ownsText}.`
-      : `${named.length} helpers wrote this, and it is one pull request because it is one change:\n${named.map((one) => `- \`${one.title}\`, which owns ${one.ownsText}`).join('\n')}`,
+    'The Atlas tooling writer wrote this. It copies the repo check and its workflow from the Atlas package.',
     '',
     `**Why.** ${String(why ?? '').trim() || 'Not given.'}`,
     '',
     '## What changed, and where each change came from',
     '',
-    '| File | Helper | Source | What the source says |',
-    '|---|---|---|---|',
+    '| File | Source | What the source says |',
+    '|---|---|---|',
   ];
-  for (const group of parts) {
-    for (const change of group.changes) {
-      lines.push(`| \`${escapeCell(change.path)}\` | ${escapeCell(group.helper.title)} | ${escapeCell(change.provenance.source)} | ${escapeCell(change.provenance.detail)} |`);
-    }
-  }
+  for (const change of changes) lines.push(`| \`${escapeCell(change.path)}\` | ${escapeCell(change.provenance.source)} | ${escapeCell(change.provenance.detail)} |`);
   lines.push(
     '',
     '## How to read this',
     '',
-    `1. Every file above is instruction class. It steers agents, so a person merges it${repo ? ` in ${repo}` : ''}.`,
+    `1. Both files are rule files. They steer agents, so a person merges this${repo ? ` in ${repo}` : ''}.`,
     '2. An agent made every change. No person edited these files by hand.',
     `3. "Source" is one of: ${PROVENANCE_SOURCES.join(', ')}.`,
     '',
-    `Label: \`${HELPER_LABEL}\`. Authority: Arjunkhera/atlas, amendment A1.6, section 5, slice L2 stage one.`,
+    `Label: \`${TOOLING_LABEL}\`.`,
     '',
   );
   return lines.join('\n');
@@ -72,8 +76,8 @@ export function provenanceBody({ helper, helpers, why, changes, groups, repo = n
 
 // Write a checked change set into a working tree. It writes files and nothing
 // else: no branch, no commit, no network. `open` below does the rest.
-export function applyChanges(root, helperId, changes) {
-  const helper = checkChanges(helperId, changes);
+export function applyChanges(root, changes) {
+  checkChanges(changes);
   const written = [];
   for (const change of changes) {
     const path = join(root, change.path);
@@ -81,41 +85,36 @@ export function applyChanges(root, helperId, changes) {
     writeFileSync(path, change.contents);
     written.push(change.path);
   }
-  return { helper, written };
+  return { written };
 }
 
 const run = (command, args, cwd) => execFileSync(command, args, { cwd, encoding: 'utf8', timeout: 120_000, maxBuffer: 8 * 1024 * 1024, env: childEnvironment() }).trim();
 
 // The whole pull request, live. Needs git and the GitHub command line.
 //
-// It never merges. A person merges every file a helper writes, because every
-// one of them steers agents.
-export function open({ root, helperId, changes, groups, why, branch, title, base = null, label = HELPER_LABEL, dryRun = false, exec = run }) {
-  const wanted = groups ?? [{ helperId, changes }];
-  const checked = checkAll(wanted);
-  const all = checked.flatMap((group) => group.changes);
-  // A dry run writes nothing. The first version applied the changes and then
-  // printed "Nothing was pushed", which was true and misleading (acceptance
-  // review of batch 16, finding S3-5).
-  if (!dryRun) for (const group of checked) applyChanges(root, group.helper.id, group.changes);
+// It never merges. A person merges it, because both files steer agents.
+export function open({ root, changes, why, branch, title, base = null, label = TOOLING_LABEL, dryRun = false, exec = run }) {
+  checkChanges(changes);
+  // A dry run writes nothing.
+  if (!dryRun) applyChanges(root, changes);
   const repo = (() => { try { return exec('gh', ['repo', 'view', '--json', 'nameWithOwner', '--jq', '.nameWithOwner'], root); } catch { return null; } })();
-  const body = provenanceBody({ groups: checked, why, repo });
+  const body = provenanceBody({ why, changes, repo });
   const onto = base ?? exec('git', ['symbolic-ref', '--short', 'HEAD'], root);
-  const helper = checked[0].helper;
-  if (dryRun) return { helper, helpers: checked.map((group) => group.helper), repo, branch, title, body, base: onto, written: all.map((change) => change.path), opened: false };
+  const written = changes.map((change) => change.path);
+  if (dryRun) return { repo, branch, title, body, base: onto, written, opened: false };
 
   exec('git', ['checkout', '-b', branch], root);
-  exec('git', ['add', '--', ...all.map((change) => change.path)], root);
+  exec('git', ['add', '--', ...written], root);
   exec('git', ['commit', '-m', title, '-m', body], root);
   exec('git', ['push', '-u', 'origin', branch], root);
   // A label that does not exist yet makes `gh pr create` fail, so it is made
   // first. A label that already exists makes that call fail instead, and that
   // failure is the expected one.
-  try { exec('gh', ['label', 'create', label, '--description', 'Written by an Atlas helper. A person merges it.', '--color', 'C5A882'], root); } catch { /* it already exists */ }
+  try { exec('gh', ['label', 'create', label, '--description', 'Written by the Atlas tooling writer. A person merges it.', '--color', 'C5A882'], root); } catch { /* it already exists */ }
   // --head names the branch. `git push -u` does not always record the upstream
   // in a shallow clone, and then `gh pr create` refuses with "you must first
   // push the current branch" although the branch is already on GitHub
   // (measured on an Engram clone, 2026-09-20).
   const url = exec('gh', ['pr', 'create', '--title', title, '--body', body, '--label', label, '--base', onto, '--head', branch], root);
-  return { helper, helpers: checked.map((group) => group.helper), repo, branch, title, body, base: onto, written: all.map((change) => change.path), opened: true, url };
+  return { repo, branch, title, body, base: onto, written, opened: true, url };
 }

package/door/lib/ste-words.json

@@ -0,0 +1,51 @@
+{
+  "about": "Words that ASD-STE100 does not approve, each with the plain word to use instead. The check flags them and never rewrites. Add a word here with its plain word; remove one only by a decision.",
+  "words": {
+    "utilize": "use",
+    "utilise": "use",
+    "leverage": "use",
+    "facilitate": "help",
+    "commence": "start",
+    "terminate": "stop",
+    "approximately": "about",
+    "additional": "more",
+    "additionally": "also",
+    "assist": "help",
+    "obtain": "get",
+    "prior": "before",
+    "subsequent": "next",
+    "subsequently": "then",
+    "numerous": "many",
+    "sufficient": "enough",
+    "endeavor": "try",
+    "attempt": "try",
+    "ascertain": "find",
+    "demonstrate": "show",
+    "indicate": "show",
+    "initiate": "start",
+    "modify": "change",
+    "purchase": "buy",
+    "regarding": "about",
+    "therefore": "thus",
+    "however": "but",
+    "furthermore": "also",
+    "moreover": "also",
+    "nevertheless": "but",
+    "whereas": "but",
+    "whilst": "while",
+    "amongst": "among",
+    "simply": "(remove it)",
+    "basically": "(remove it)",
+    "essentially": "(remove it)",
+    "very": "(remove it, or use an exact word)",
+    "really": "(remove it)",
+    "actually": "(remove it)",
+    "etc": "(name each item)",
+    "e.g": "for example",
+    "i.e": "that is",
+    "via": "through",
+    "robust": "strong",
+    "seamless": "(say what it does)",
+    "seamlessly": "(say what it does)"
+  }
+}

package/door/lib/ste.mjs

@@ -0,0 +1,199 @@
+// The STE check. It measures a markdown or HTML page against the limits of
+// ASD-STE100 that code can measure, and flags what breaks them. It never
+// rewrites a word: a person or an agent fixes the text.
+//
+// The limits: 20 words in a sentence of a numbered step, 25 words in any
+// other sentence, 6 sentences in a paragraph, and no word from the list in
+// ste-words.json. Code, block quotes and quoted words are exempt, because
+// they are not the writer's own prose.
+//
+// `--share` adds the privacy filter, with no exemption for quotes: a quoted
+// email address still leaves with the page.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, extname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { privacyFindings, loadPrivateTerms } from './privacy.mjs';
+
+export const LIMITS = Object.freeze({ step: 20, sentence: 25, paragraph: 6 });
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const WORDS = Object.freeze(JSON.parse(readFileSync(join(HERE, 'ste-words.json'), 'utf8')).words);
+
+// Each listed word, with its common forms.
+function forms(word) {
+  const out = new Set([word, `${word}s`, `${word}es`, `${word}d`, `${word}ed`, `${word}ing`]);
+  if (word.endsWith('y')) { out.add(`${word.slice(0, -1)}ies`); out.add(`${word.slice(0, -1)}ied`); }
+  if (word.endsWith('e')) out.add(`${word.slice(0, -1)}ing`);
+  return [...out];
+}
+const FORM_TO_WORD = new Map(Object.keys(WORDS).flatMap((word) => forms(word).map((form) => [form, word])));
+
+// ------------------------------------------------------------- reading a page
+
+// Code and quoted words become one placeholder word each: they are not the
+// writer's prose, but a name still takes a place in the sentence. The quote
+// marks go with the words they hold.
+function stripInline(text) {
+  return text
+    .replace(/`[^`]*`/g, ' Code ')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/<https?:[^>]*>/g, ' ')
+    .replace(/https?:\/\/\S+/g, ' ')
+    .replace(/"[^"\n]*"/g, ' Quote ')
+    .replace(/“[^”\n]*”/g, ' Quote ')
+    .replace(/(^|[\s(])'[^'\n]+'(?=[\s.,;:)]|$)/g, '$1 Quote ')
+    .replace(/\*\*|__|\*|~~/g, '')
+    .replace(/<[^>]+>/g, ' ');
+}
+
+// Markdown into units: each unit is a paragraph, a list item or a table cell,
+// with the line it starts on and whether it is a numbered step.
+export function markdownUnits(text) {
+  const lines = text.split('\n');
+  const units = [];
+  let current = null;
+  let fence = null;
+  let comment = false;
+  const close = () => { if (current && current.text.trim()) units.push(current); current = null; };
+  let index = 0;
+  if (lines[0] === '---') {
+    const end = lines.indexOf('---', 1);
+    if (end > 0) index = end + 1;
+  }
+  for (; index < lines.length; index += 1) {
+    const line = lines[index];
+    const number = index + 1;
+    const fenceMark = /^\s*(```|~~~)/.exec(line);
+    if (fence) { if (fenceMark && fenceMark[1] === fence) fence = null; continue; }
+    if (fenceMark) { close(); fence = fenceMark[1]; continue; }
+    if (!line.trim()) { close(); continue; }
+    if (/^\s*>/.test(line)) { close(); continue; }
+    if (comment) { if (line.includes('-->')) comment = false; continue; }
+    if (/^\s*<!--/.test(line)) { close(); comment = !line.includes('-->'); continue; }
+    if (/^\s*\|/.test(line)) {
+      close();
+      if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
+      for (const cell of line.split('|').slice(1, -1)) if (cell.trim()) units.push({ line: number, step: false, text: cell });
+      continue;
+    }
+    if (/^\s{0,3}#{1,6}\s/.test(line)) { close(); units.push({ line: number, step: false, text: line.replace(/^\s*#+\s*/, '') }); continue; }
+    const numbered = /^\s*\d+[.)]\s+(.*)$/.exec(line);
+    const bullet = /^\s*[-*+]\s+(.*)$/.exec(line);
+    if (numbered || bullet) { close(); current = { line: number, step: Boolean(numbered), text: (numbered ?? bullet)[1] }; continue; }
+    if (current) current.text += ` ${line.trim()}`;
+    else current = { line: number, step: false, text: line.trim() };
+  }
+  close();
+  return units.map((unit) => ({ ...unit, text: stripInline(unit.text) }));
+}
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: '\'', nbsp: ' ', mdash: '—', ndash: '–', rsquo: '’', lsquo: '‘', ldquo: '“', rdquo: '”', hellip: '…' };
+const decode = (text) => text.replace(/&(#\d+|#x[0-9a-f]+|[a-z]+);/gi, (whole, name) => {
+  if (name[0] === '#') return String.fromCodePoint(name[1].toLowerCase() === 'x' ? parseInt(name.slice(2), 16) : Number(name.slice(1)));
+  return ENTITIES[name.toLowerCase()] ?? whole;
+});
+
+// HTML into the same units. Each block element is a unit; an item of an
+// ordered list is a step. Script, style, code, pre and quotes are exempt.
+export function htmlUnits(text) {
+  // Each replacement keeps its line breaks, so a line number in the body is
+  // the line number in the page.
+  const blank = (match) => match.replace(/[^\n]/g, ' ');
+  const word = (name) => (match) => ` ${name} ${match.replace(/[^\n]/g, '')}`;
+  const body = text
+    .replace(/<!--[\s\S]*?-->/g, blank)
+    .replace(/<(script|style|pre|blockquote|svg|template|title|head)\b[\s\S]*?<\/\1>/gi, blank)
+    .replace(/<code\b[\s\S]*?<\/code>/gi, word('Code'))
+    .replace(/<q\b[\s\S]*?<\/q>/gi, word('Quote'));
+  const lineAt = (offset) => body.slice(0, offset).split('\n').length;
+  const units = [];
+  const BLOCK = /<(p|li|h[1-6]|td|th|dt|dd|figcaption|caption|summary|label|button)\b[^>]*>([\s\S]*?)<\/\1>/gi;
+  for (const match of body.matchAll(BLOCK)) {
+    const inner = match[2];
+    if (/<(p|li|ul|ol|div|table)\b/i.test(inner)) continue;
+    let step = false;
+    if (match[1].toLowerCase() === 'li') {
+      const before = body.slice(0, match.index);
+      const lastOl = before.lastIndexOf('<ol');
+      const lastUl = before.lastIndexOf('<ul');
+      const closedOl = before.lastIndexOf('</ol');
+      step = lastOl > lastUl && lastOl > closedOl;
+    }
+    const plain = decode(stripInline(inner.replace(/<br\s*\/?>/gi, ' '))).replace(/\s+/g, ' ').trim();
+    if (plain) units.push({ line: lineAt(match.index), step, text: plain });
+  }
+  return units;
+}
+
+// ------------------------------------------------------------- measuring
+
+// A sentence ends at . ! or ? before a space and a capital, a digit or an
+// opening mark, or at the end of the unit. A colon before a list, and a
+// heading, end nothing.
+export function sentences(text) {
+  const clean = text.replace(/\s+/g, ' ').trim();
+  if (!clean) return [];
+  return clean.split(/(?<=[.!?])\s+(?=[A-Z0-9(“"'])/).map((one) => one.trim()).filter((one) => /[A-Za-z0-9]/.test(one));
+}
+
+export const words = (sentence) => sentence.split(/\s+/).filter((token) => /[A-Za-z0-9]/.test(token));
+
+export function measure(units) {
+  const findings = [];
+  for (const unit of units) {
+    const list = sentences(unit.text);
+    if (list.length > LIMITS.paragraph) findings.push({ line: unit.line, rule: 'paragraph', why: `${list.length} sentences in one paragraph; the limit is ${LIMITS.paragraph}` });
+    const limit = unit.step ? LIMITS.step : LIMITS.sentence;
+    for (const sentence of list) {
+      const count = words(sentence).length;
+      if (count > limit) findings.push({ line: unit.line, rule: unit.step ? 'step-sentence' : 'sentence', why: `${count} words in one sentence${unit.step ? ' of a numbered step' : ''}; the limit is ${limit}: "${sentence.split(/\s+/).slice(0, 8).join(' ')} …"` });
+    }
+    const seen = new Set();
+    for (const token of unit.text.toLowerCase().match(/[a-z]+(?:\.[a-z])?/g) ?? []) {
+      const word = FORM_TO_WORD.get(token);
+      if (word && !seen.has(token)) { seen.add(token); findings.push({ line: unit.line, rule: 'word', why: `"${token}" is not an approved word; use ${WORDS[word]}` }); }
+    }
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------- files
+
+const READABLE = new Set(['.md', '.markdown', '.html', '.htm']);
+const SKIP = new Set(['node_modules', '.git']);
+
+export function pagesUnder(path) {
+  if (!existsSync(path)) throw new Error(`${path} does not exist`);
+  if (statSync(path).isFile()) return [path];
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir).sort()) {
+      if (SKIP.has(entry)) continue;
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full);
+      else if (READABLE.has(extname(entry).toLowerCase())) out.push(full);
+    }
+  };
+  walk(path);
+  return out;
+}
+
+export function checkText(text, { html = false, share = false, terms = [] } = {}) {
+  const findings = measure(html ? htmlUnits(text) : markdownUnits(text));
+  if (share) findings.push(...privacyFindings(text, { terms }).map((finding) => ({ ...finding, rule: `privacy:${finding.rule}` })));
+  return findings.sort((a, b) => a.line - b.line);
+}
+
+export function checkPaths(paths, { share = false, terms = null, base = process.cwd() } = {}) {
+  const own = terms ?? (share ? loadPrivateTerms() : []);
+  const results = [];
+  for (const path of paths) {
+    for (const file of pagesUnder(path)) {
+      const html = /\.html?$/i.test(file);
+      const findings = checkText(readFileSync(file, 'utf8'), { html, share, terms: own });
+      results.push({ file: relative(base, file) || file, findings });
+    }
+  }
+  return results;
+}

package/door/lib/tooling.mjs

@@ -1,4 +1,4 @@
-// The tooling helper. It writes and refreshes the two files Atlas puts in a
+// The tooling writer. It writes and refreshes the two files Atlas puts in a
 // repository, and it needs no model and no network to do it.
 //
 // Milestone M2, slice L2 stage one, done line 1: "The tooling helper writes
@@ -53,7 +53,7 @@ export function isPackageRepo(root, packageRoot) {
   } catch { return false; }
 }
 
-// May the helper write into this repository? Returns nothing, or throws a
+// May the tooling writer write into this repository? Returns nothing, or throws a
 // refusal that says what to do instead.
 const readWorkflow = (root) => { const full = join(root, WORKFLOW_PATH); return existsSync(full) ? readFileSync(full, 'utf8') : null; };
 

package/package.json

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