@arjunkhera/atlas 0.4.44 → 0.4.46

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // The atlas command: install, upgrade, doctor, check, status, the tooling
-// writer, the kind drift report, the code-read resolver, the STE check, the
+// writer, the code-read resolver, the STE check, the
 // design check and page builder, the tests verbs (the link check and the
 // test kit writer), the upkeep check, and the judge of the fresh-agent test.
 //
@@ -18,7 +18,6 @@ import { spawnSync } from 'node:child_process';
 import { open } from './lib/pull-request.mjs';
 import { write as writeTooling, changes as toolingChanges, ToolingRefusal, CHECK_PATH, WORKFLOW_PATH } from './lib/tooling.mjs';
 import { statusMany, copies } from './lib/status.mjs';
-import { drift, kindsFromRegistry, fileKind } from './lib/kind-drift.mjs';
 import { scan, toText, verdict, CHECK_VERSION, SPECS } from '../shape/check.mjs';
 import { packagePackageVersion } from './lib/releases.mjs';
 import { install, upgrade, doctor } from './lib/install.mjs';
@@ -54,9 +53,8 @@ const HELP = `atlas — the door into a repo's Atlas files
   atlas status --root <repo>           is the repo's check current, behind, unknown or missing
       --all                            every Atlas copy in the repo: the check, its workflow, each test kit, each pinned Atlas version
       --json                           print the rows as JSON: type, path, state, have, want, why
-  atlas kind-drift --root <repo> --record-kind <kinds>
-                                       does atlas.yaml agree with the repo record
   atlas check --root <repo>            run the repo shape check here
+      --json                           print the report as JSON, with the counts of parts, procedures and jobs
 
   atlas code-read resolve …            resolve the citations of a code digest
 
@@ -210,8 +208,7 @@ A person merges every file the tooling writer writes.
 export const FLAGS = Object.freeze({
   tooling: { root: 'optional', branch: 'optional', 'replace-unknown': 'switch', workflow: 'switch', 'dry-run': 'switch' },
   status: { root: 'optional', all: 'switch', json: 'switch' },
-  'kind-drift': { root: 'optional', 'record-kind': 'value', registry: 'value', repo: 'value' },
-  check: { root: 'optional', repo: 'value', 'fail-on': 'value' },
+  check: { root: 'optional', repo: 'value', 'fail-on': 'value', json: 'switch' },
   ste: { share: 'switch', terms: 'value' },
   design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
   view: { product: 'value', name: 'value', out: 'value' },
@@ -338,40 +335,6 @@ function copiesCommand(roots, { all, json }) {
   return repos.some((repo) => repo.rows.some((one) => bad.includes(one.state))) ? 1 : 0;
 }
 
-function kindDriftCommand(chosen) {
-  const root = rootOf(chosen);
-  let recordKind = chosen['record-kind'] ?? null;
-  if (!recordKind && chosen.registry) {
-    const kinds = kindsFromRegistry(JSON.parse(readFileSync(resolve(chosen.registry), 'utf8')));
-    const repo = chosen.repo ?? null;
-    recordKind = repo ? kinds[repo] ?? null : null;
-    if (!repo) {
-      // One checkout, so only the registry row that names THIS repo can be
-      // compared. Comparing every row against one root invented drift that was
-      // not there (acceptance review of batch 16, finding S2-6).
-      const here = fileKind(root);
-      if (!here.repo) { line(`${root} has no atlas.yaml, or its atlas.yaml names no repo, so no registry row can be matched to it.`); return 1; }
-      recordKind = kinds[here.repo] ?? null;
-      const others = Object.keys(kinds).filter((id) => id !== here.repo);
-      const report = drift([{ root, recordKind, recordRepo: here.repo }]);
-      for (const row of report.rows) line(`${row.state.toUpperCase().padEnd(10)} ${row.repo}  file=${row.file_kind ?? '-'} record=${row.record_kind ?? '-'}  ${row.why}`);
-      if (!(here.repo in kinds)) line(`The registry holds no row for ${here.repo}. Register it with the repo_add verb.`);
-      if (others.length) line(`Not this checkout, so not read: ${others.join(', ')}. Point --root at each one.`);
-      return report.drifting ? 1 : 0;
-    }
-  }
-  const report = drift([{ root, recordKind }]);
-  for (const row of report.rows) {
-    line(`${row.state.toUpperCase()}  ${row.repo ?? row.root}`);
-    line(`  atlas.yaml   kind ${row.file_kind ?? '(none)'}   spec ${row.spec ?? '(none)'}`);
-    line(`  repo record  kind ${row.record_kind ?? '(not given)'}`);
-    line(`  ${row.why}`);
-  }
-  line('');
-  line('Which of the two is the source is open question O-9. This report picks no winner.');
-  return report.drifting ? 1 : 0;
-}
-
 function steCommand(chosen) {
   const paths = chosen._.slice(1);
   if (!paths.length) throw new Error('give a file or a folder: atlas ste <path> [--share]');
@@ -484,6 +447,12 @@ function checkCommand(chosen) {
   const root = rootOf(chosen);
   const report = scan({ root, repoId: chosen.repo ?? null });
   const decision = verdict(report, chosen['fail-on'] ?? 'error');
+  // The O7 count is one command (roadmap R62 line 6): the report, its counts
+  // of listed parts, procedures and jobs, and the verdict.
+  if (chosen.json) {
+    process.stdout.write(`${JSON.stringify({ ...report, fail_on: chosen['fail-on'] ?? 'error', green: decision.green, why: decision.why }, null, 2)}\n`);
+    return decision.green ? 0 : 1;
+  }
   process.stdout.write(toText(report));
   // A report, never a reason for red: the list is an owner-only key.
   const list = mergeList(root);
@@ -509,7 +478,6 @@ export async function main(argv = process.argv.slice(2)) {
     case 'doctor': return doctor({ packageRoot: PACKAGE_ROOT, options: chosen, line });
     case 'tooling': return toolingCommand(chosen);
     case 'status': return statusCommand(chosen);
-    case 'kind-drift': return kindDriftCommand(chosen);
     case 'check': return checkCommand(chosen);
     case 'ste': return steCommand(chosen);
     case 'design': return designCommand(chosen);

package/door/lib/owner-only.mjs

@@ -215,7 +215,7 @@ export function atlasYamlCause(baseText, headText, rules) {
   if (!changed.length) return 'atlas.yaml text changed outside its keys';
   for (const key of changed) {
     if (rules.fixed.includes(key)) return `atlas.yaml key ${key} changed`;
-    if (!rules.add_only.includes(key)) return `atlas.yaml key ${key} changed, and R62 does not list it yet`;
+    if (!rules.add_only.includes(key)) return `atlas.yaml key ${key} changed, and the key list in owner-only.yaml names no rule for it`;
     if (!onlyAdds(a[key], b[key])) return `atlas.yaml key ${key}: an entry was removed, moved or changed`;
   }
   return null;

package/door/lib/tooling.mjs

@@ -17,7 +17,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
-import { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH, WORKFLOW_TEMPLATE, SHAPE_JOB_TEXT, shapeJobOf, CHECK_VERSION, sha256, parseYaml } from '../../shape/check.mjs';
+import { CHECK_PATH, WORKFLOW_PATH, OLD_WORKFLOW_PATH, WORKFLOW_TEMPLATE, SHAPE_JOB_TEXT, shapeJobOf, CHECK_VERSION, SPECS, SPEC_3, sha256, parseYaml } from '../../shape/check.mjs';
 import { packagedCheck, packagePackageVersion, PACKAGE_CHECK_SOURCE } from './releases.mjs';
 import { status } from './status.mjs';
 import { PR_TEMPLATE_PATH } from './upkeep.mjs';
@@ -122,12 +122,43 @@ export function isPackageRepo(root, packageRoot) {
 // refusal that says what to do instead.
 const readWorkflow = (root) => { const full = join(root, WORKFLOW_PATH); return existsSync(full) ? readFileSync(full, 'utf8') : null; };
 
+// The spec 3 lines for a repo whose atlas.yaml is older (roadmap R62). Check
+// version 10 reads spec 3 only, so a copy written into a spec 2 repo would turn
+// its own check red. The lines name the parts this repo already carries: the
+// two entry maps, the index and the two tooling files, plus the rules and a
+// linter config where the repo has them.
+export function specThreeLines(root) {
+  const parts = ['claude-md', 'agents-md'];
+  if (existsSync(join(root, '.claude', 'rules'))) parts.push('rules');
+  parts.push('docs-index', 'check-file', 'gate-workflow');
+  const linters = SPEC_3.files.flatMap((file) => file.parts).find((part) => part.id === 'linters').candidates;
+  if (linters.some((path) => existsSync(join(root, path)))) parts.push('linters');
+  return [`parts: [${parts.join(', ')}]`];
+}
+
+// The spec version atlas.yaml declares, or null when there is no file or it
+// does not read. The check reports those cases itself.
+function declaredSpec(root) {
+  const file = join(root, 'atlas.yaml');
+  if (!existsSync(file)) return null;
+  try { return parseYaml(readFileSync(file, 'utf8'))?.spec ?? null; } catch { return null; }
+}
+
 export function mayWrite(root, packageRoot, { replaceUnknown = false, workflowOnly = false } = {}) {
   const pkg = packagedCheck(packageRoot);
   const own = isPackageRepo(root, packageRoot);
   if (!pkg.latest && !own) {
     throw new ToolingRefusal(`this package's ${PACKAGE_CHECK_SOURCE} is ${pkg.row ? 'not the newest release' : 'in no release'} of the check, so it is not written into another repo. Use a released Atlas.`);
   }
+  const spec = declaredSpec(root);
+  if (spec !== null && !workflowOnly && !SPECS[spec]) {
+    throw new ToolingRefusal([
+      `atlas.yaml is spec ${spec}. Check version ${CHECK_VERSION} reads spec ${Object.keys(SPECS).join(', ')} only.`,
+      'Set spec: 3, remove the kind: line, and add:',
+      ...specThreeLines(root),
+      'Then run atlas tooling again. Nothing was written.',
+    ].join('\n'));
+  }
   const now = status({ root, packageRoot });
   if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot) && !pinnedNeedWrite(root, packageRoot) && !oldWorkflow(root)) {
     throw new ToolingRefusal(`this repo's check is already current. ${readWorkflow(root) === WORKFLOW_TEMPLATE || workflowKept(root) ? 'Both files match the package, so there is nothing to write.' : 'Its workflow file differs from the package; pass --workflow to rewrite only that file.'}`, { current: true });

package/door/lib/upkeep.mjs

@@ -7,7 +7,8 @@
 //
 // 1. Docs index. docs/index.md lists each .md file under docs/. A file in a
 //    design folder (a folder that holds design.yaml) counts as listed when the
-//    index lists that folder's design.yaml. Each listed path exists.
+//    index lists that folder's design.yaml. Each listed path exists. The rule
+//    is the shape check's own, docsIndexRule (roadmap R62 line 5).
 // 2. Dead links. Each relative link in a tracked .md file names a file or a
 //    folder that exists. archive/ is frozen, and test fixtures are planted on
 //    purpose, so both are skipped; so is text inside code.
@@ -24,8 +25,9 @@
 //    and a stale page is listed.
 //
 // It reads the tree and the event file, and writes nothing.
-import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join, dirname, posix, resolve } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { DOCS_INDEX_PATH, docsIndexRule, markdownFiles, proseOf, linkTargets } from '../../shape/check.mjs';
 import { listChanged } from './changed-tests.mjs';
 import { docSourceFindings, replay } from './doc-sources.mjs';
 import { proceduresCommand } from './procedure-steps.mjs';
@@ -37,62 +39,13 @@ import { changedDocFindings } from './changed-docs.mjs';
 // touched doc with no update and no mark a note, not a finding.
 export const TOUCHED_DOCS_GATE = true;
 
-const INDEX = 'docs/index.md';
-const SKIP_DIRS = new Set(['node_modules', 'archive', 'fixtures']);
+const INDEX = DOCS_INDEX_PATH;
 const MAX_LISTED = 20;
 
-// Every .md file under the root, as a posix path. Dot folders, node_modules,
-// archive/ and any folder named fixtures are skipped.
-export function markdownFiles(root, under = '') {
-  const out = [];
-  const walk = (rel) => {
-    let entries;
-    try { entries = readdirSync(join(root, rel), { withFileTypes: true }); } catch { return; }
-    for (const entry of entries) {
-      if (entry.name.startsWith('.')) continue;
-      const path = rel ? `${rel}/${entry.name}` : entry.name;
-      if (entry.isDirectory()) { if (!SKIP_DIRS.has(entry.name)) walk(path); }
-      else if (entry.isFile() && entry.name.endsWith('.md')) out.push(path);
-    }
-  };
-  walk(under);
-  return out.sort();
-}
-
-// Text outside code: fenced blocks of three or more marks, and inline code.
-export function proseOf(text) {
-  const lines = String(text ?? '').split('\n');
-  const kept = [];
-  let fence = null;
-  for (const one of lines) {
-    const open = one.match(/^\s*(`{3,}|~{3,})/);
-    if (fence) {
-      if (open && open[1][0] === fence[0] && open[1].length >= fence.length && !one.trim().slice(open[1].length).trim()) fence = null;
-      kept.push('');
-      continue;
-    }
-    if (open) { fence = open[1]; kept.push(''); continue; }
-    kept.push(one.replace(/`+[^`\n]*`+/g, ''));
-  }
-  return kept.join('\n');
-}
-
-// The relative link targets in one markdown text, with their line numbers.
-export function linkTargets(text) {
-  const out = [];
-  proseOf(text).split('\n').forEach((one, index) => {
-    for (const [, angled, bare] of one.matchAll(/\]\(\s*(?:<([^>\n]+)>|([^)\s]+))(?:\s+"[^"]*")?\s*\)/g)) {
-      const raw = angled ?? bare;
-      const target = raw.split('#')[0].split('?')[0];
-      if (!target || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith('#')) continue;
-      if (/[{}$*\\]/.test(target)) continue;
-      let decoded = target;
-      try { decoded = decodeURIComponent(target); } catch { /* keep it as written */ }
-      out.push({ target: decoded, line: index + 1 });
-    }
-  });
-  return out;
-}
+// markdownFiles, proseOf and linkTargets live in the shape check, beside the
+// one docs index rule (roadmap R62 line 5). They stay exported here, so their
+// readers keep one door.
+export { markdownFiles, proseOf, linkTargets };
 
 export function deadLinks(root) {
   const dead = [];
@@ -106,32 +59,11 @@ export function deadLinks(root) {
   return dead;
 }
 
-// The nearest folder at or above `file` that holds design.yaml, or null.
-function designFolderOf(root, file) {
-  let dir = posix.dirname(file);
-  while (dir && dir !== '.' && dir !== 'docs') {
-    if (existsSync(join(root, dir, 'design.yaml'))) return dir;
-    dir = posix.dirname(dir);
-  }
-  return null;
-}
-
+// The docs index rule is the shape check's, so the check and this command
+// give one count on one tree (roadmap R62 line 5).
 export function docsIndex(root) {
-  if (!existsSync(join(root, 'docs')) || !statSync(join(root, 'docs')).isDirectory()) return { checked: false, unlisted: [], gone: [] };
-  if (!existsSync(join(root, INDEX))) return { checked: true, missing: true, unlisted: markdownFiles(root, 'docs'), gone: [] };
-  const listed = new Set();
-  for (const { target } of linkTargets(readFileSync(join(root, INDEX), 'utf8'))) {
-    if (target.startsWith('/')) continue;
-    const path = posix.normalize(posix.join('docs', target)).replace(/\/$/, '');
-    if (path.startsWith('docs/')) listed.add(path);
-  }
-  const unlisted = markdownFiles(root, 'docs').filter((path) => {
-    if (path === INDEX || listed.has(path)) return false;
-    const folder = designFolderOf(root, path);
-    return !(folder && listed.has(`${folder}/design.yaml`));
-  });
-  const gone = [...listed].filter((path) => !existsSync(join(root, path))).sort();
-  return { checked: true, unlisted, gone };
+  const { checked, missing, unlisted, gone } = docsIndexRule(root);
+  return missing ? { checked, missing, unlisted, gone } : { checked, unlisted, gone };
 }
 
 const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;

package/owner-only.yaml

@@ -218,22 +218,30 @@ floor:
 # does not follow names out of it (shape/check.mjs, the exemption).
 entry_map: docs/index.md
 
-# The keys of atlas.yaml whose change is always owner-only. A change to any
-# other key is owner-only too, until roadmap R62 lists the safe ones. The one
-# change that passes is an addition under `parts:`.
+# The key rule for atlas.yaml (roadmap R2 line 11, R62 line 3). Each key of
+# atlas.yaml is on one of the two lists. A pull request may add entries under
+# an add_only key and merge on green; any other change to it, and any change
+# to a fixed key, comes to the owner. A key on neither list comes to the owner
+# too, until a pull request puts it on one.
 atlas_yaml:
   add_only:
     - parts
+    - procedures
+    - files
+    - kinds_of_change
   fixed:
-    - owner_only
+    - spec
+    - product
+    - repo
     - areas
+    - owner_only
     - required_checks
-    - product
     - product_paths
-    - repo
-    - kind
-    - kinds
     - up_to_date
     - brake
+    - live
+    - jobs
+    - design
     - generated
-    - spec
+    - verbatim
+    - private_terms

package/package.json

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