@arjunkhera/atlas 0.4.3 → 0.4.5

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -33,6 +33,7 @@ import { verdictCommand as testsVerdict, namedCommand as testsNamed, rerunComman
 import { runKept } from '../tests/kept.mjs';
 import { sweepCommand as testsSweep, coversCommand as testsCovers } from '../tests/sweep.mjs';
 import { issuesCommand as testsIssues } from './lib/issues.mjs';
+import { jobsCommand } from './lib/jobs.mjs';
 import { changedCommand as testsChanged } from './lib/changed-tests.mjs';
 import { beforeCommand as testsBefore } from './lib/fails-before.mjs';
 import { afterCommand as testsAfter } from './lib/passes-after.mjs';
@@ -129,6 +130,14 @@ const HELP = `atlas — the door into a repo's Atlas files
       --tests <dir>                    the test folder of the area; default test. The test files are in <dir>/scenarios
       --evidence <dir>                 where the evidence files are; default <area>/test/evidence
 
+  atlas jobs check --root <repo> --repo <owner/name>   the watcher: run the check of each Atlas job that atlas.yaml names; findings as JSON
+      --branch <name>                  the default branch; default GitHub's answer
+      --out <file>                     write the JSON here; default the terminal
+  atlas jobs file --findings <file> --repo <owner/name>   open one atlas-job issue for each new finding of a jobs check; never closes one
+      --max <n>                        open at most n issues in one run; default 10. The rest are listed, and the exit is 1
+      --dry-run                        print what it would open; change nothing
+                                       The token is only GITHUB_TOKEN. The atlas-jobs workflow runs both, once a day
+
   atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, and in a pull request its tracker item
       --event <file>                   the GitHub pull request event; adds the item check
       --json                           print JSON
@@ -180,6 +189,7 @@ export const FLAGS = Object.freeze({
   design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
   view: { product: 'value', name: 'value', out: 'value' },
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', head: 'value', list: 'value', side: 'value', old: 'value', new: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
+  jobs: { root: 'optional', repo: 'value', branch: 'value', out: 'value', findings: 'value', max: 'value', 'dry-run': 'switch' },
   upkeep: { root: 'optional', event: 'value', json: 'switch' },
   gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
@@ -413,6 +423,10 @@ async function testsCommand(chosen) {
   throw new Error(`there is no tests verb "${what ?? ''}". Use check, write, proof, verdict, named, changed, before, after, sweep, covers, kept, issues or rerun.`);
 }
 
+function jobsVerb(chosen) {
+  return jobsCommand({ what: chosen._[1], root: rootOf(chosen), repo: chosen.repo, branch: chosen.branch, out: chosen.out, findings: chosen.findings, max: chosen.max, dryRun: Boolean(chosen['dry-run']), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
+}
+
 function upkeepVerb(chosen) {
   return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json) }, rootOf(chosen), line);
 }
@@ -457,6 +471,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'design': return designCommand(chosen);
     case 'view': return viewCommand(chosen);
     case 'tests': return testsCommand(chosen);
+    case 'jobs': return jobsVerb(chosen);
     case 'upkeep': return upkeepVerb(chosen);
     case 'gate': return gateVerb(chosen);
     case 'judge': return judgeVerb(chosen);

package/door/jobs/red-main.yaml

@@ -0,0 +1,15 @@
+# An Atlas job (the routines design, records part). A job does nothing until a
+# repo names it in its atlas.yaml:
+#
+#   jobs:
+#     atlas: [red-main]
+#
+# The check is Atlas code (door/lib/jobs.mjs). It reads the runs of the main
+# branch only, never a run from a fork. `fields` are the typed fields that a
+# finding of this job may hold. Atlas code drops every other field.
+title: The newest CI run on the main branch passes
+when: red-main
+needs: [tests]
+act: atlas:red-main
+may: pull-request
+fields: [workflow, run_id, head_sha, conclusion]

package/door/kit-releases.json

@@ -47,6 +47,10 @@
     {
       "kit_sha256": "8d6ae3c4dede74bafe292a992de3ef650e5c5566fb282081a9de23b8d30d9025",
       "first_package": "0.3.39"
+    },
+    {
+      "kit_sha256": "41d64800daf644174dd1daef1c95ccc2ca7a8460dbe3e36bcf2625d05fb0479e",
+      "first_package": "0.3.42"
     }
   ]
 }

package/door/lib/gate.mjs

@@ -206,9 +206,17 @@ export function readyCommand({ repo, pr, answer }, line, gh = ghApi) {
   const rows = checkStates(checks, checkRuns(gh, repo, sha));
   line(`atlas gate ready: #${pr} at ${sha.slice(0, 7)}, ${checks.length} required check(s) from atlas.yaml on ${pull.base.ref}.`);
   for (const row of rows) line(checkLine(row));
-  const ready = rows.every((row) => row.state === 'green');
-  line(ready ? 'READY: every required check is green. Merge with a merge commit, at this head.' : 'NOT READY: do not merge. Wait for a pending check; fix a red or missing one.');
-  return ready ? 0 : 1;
+  // Checks that ran on an old base prove nothing about the merge: two pull
+  // requests, each green alone, can turn the main branch red together (atlas#188).
+  const behind = Number(gh('GET', `repos/${repo}/compare/${encodeURIComponent(pull.base.ref)}...${sha}`)?.behind_by ?? NaN);
+  if (!(behind >= 0)) throw new GateError(`GitHub gave no compare of ${pull.base.ref} and ${sha.slice(0, 7)}.`);
+  line(`  ${behind === 0 ? '✓' : '✗'} ${(behind === 0 ? 'current' : 'behind').padEnd(8)} ${behind === 0 ? `the head holds every commit of ${pull.base.ref}` : `${pull.base.ref} has ${behind} commit(s) that the head does not hold`}`);
+  const green = rows.every((row) => row.state === 'green');
+  if (green && behind === 0) { line('READY: every required check is green, on top of the current main branch. Merge with a merge commit, at this head.'); return 0; }
+  line(behind > 0
+    ? `NOT READY: do not merge. Merge ${pull.base.ref} in, wait for green, then run ready again.`
+    : 'NOT READY: do not merge. Wait for a pending check; fix a red or missing one.');
+  return 1;
 }
 
 // The merge door hook (packages/atlas/hooks/door.mjs) reads this file before

package/door/lib/issues.mjs

@@ -22,7 +22,7 @@ import { resolve } from 'node:path';
 import { LABEL } from '../../tests/sweep.mjs';
 
 const usage = (message) => Object.assign(new Error(message), { usage: true });
-const TOKEN_SHAPE = /(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|\b[0-9a-f]{40}\b)/;
+export const TOKEN_SHAPE = /(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|\b[0-9a-f]{40}\b)/;
 const SEGMENT = /^[A-Za-z0-9_.-]+$/;
 const PAGE = 100;
 export const DEFAULT_BOT = 'github-actions[bot]';
@@ -43,7 +43,7 @@ export function apiBase(env) {
   return text.replace(/\/+$/, '');
 }
 
-async function api(base, key, method, path, body) {
+export async function api(base, key, method, path, body) {
   const response = await fetch(`${base}${path}`, {
     method,
     headers: {
@@ -63,6 +63,12 @@ async function api(base, key, method, path, body) {
 
 export const LABEL_COLOR = 'c5def5';
 export const LABEL_TEXT = 'Opened by the daily sweep of the scenario tests (atlas tests sweep)';
+// Each label an issue may carry, and its line. A label with no line here gets a plain one.
+const LABEL_TEXTS = {
+  [LABEL]: LABEL_TEXT,
+  'atlas-job': 'Opened by the Atlas watcher (atlas-jobs.yml); a runner acts on it',
+};
+const labelText = (label) => LABEL_TEXTS[label] ?? (label.startsWith('job:') ? `The Atlas job ${label.slice(4)}` : 'Opened by Atlas');
 
 // The label must exist before the first issue: a token that may only write issues may not create a label by
 // naming it in an issue. GET the label; on 404, create it. A 422 means it exists by now (a race), which is fine.
@@ -72,7 +78,7 @@ async function ensureLabel(base, key, repo, label, line) {
   const have = await api(base, key, 'GET', `/repos/${repo}/labels/${name}`);
   if (have.ok) return;
   if (have.status !== 404) { line(`label  GitHub answered ${have.status} when the label ${label} was read; going on`); return; }
-  const made = await api(base, key, 'POST', `/repos/${repo}/labels`, { name: label, color: LABEL_COLOR, description: LABEL_TEXT });
+  const made = await api(base, key, 'POST', `/repos/${repo}/labels`, { name: label, color: LABEL_COLOR, description: labelText(label) });
   if (made.ok || made.status === 422) line(`label  ${made.ok ? 'created' : 'already exists'}: ${label}`);
   else line(`label  GitHub answered ${made.status} when the label ${label} was created; going on`);
 }
@@ -99,42 +105,50 @@ export function readFindings(text) {
   return data.findings;
 }
 
-// An issue of the bot that holds the marker and stops a new one.
-const stops = (issue, marker, bot) => !issue.pull_request
+// An issue of the bot that holds the marker and stops a new one. `closedStops` says which closed issue
+// still stops one: for the sweep, one closed as not_planned.
+const sweepClosedStops = (issue) => issue.state_reason === 'not_planned';
+const stops = (issue, marker, bot, closedStops) => !issue.pull_request
   && issue.user?.login === bot
   && typeof issue.body === 'string' && issue.body.includes(marker)
-  && (issue.state === 'open' || (issue.state === 'closed' && issue.state_reason === 'not_planned'));
+  && (issue.state === 'open' || (issue.state === 'closed' && closedStops(issue)));
 
-export async function openIssues({ findings, repo, dryRun = false, max = DEFAULT_MAX, bot = DEFAULT_BOT, env = process.env, line }) {
+// `label` is the label whose issues are read for markers: the sweep's own by default. Every label of a
+// finding is made before its first issue, and the issue must carry `label`.
+export async function openIssues({ findings, repo, dryRun = false, max = DEFAULT_MAX, bot = DEFAULT_BOT, env = process.env, line, label = LABEL, closedStops = sweepClosedStops }) {
   const base = apiBase(env);
   const key = env.GITHUB_TOKEN || '';
   let known = [];
   if (!dryRun || key) {
     if (!key) throw usage('there is no token: set GITHUB_TOKEN in the environment');
-    known = await labelled(base, key, repo, LABEL);
+    known = await labelled(base, key, repo, label);
   } else line('dry run with no GITHUB_TOKEN: the existing issues are not read, so every finding shows as new.');
   const opened = [];
   const skipped = [];
   const deferred = [];
   const failed = [];
   const seen = new Set();
-  let labelEnsured = false;
+  const ensured = new Set();
   for (const f of findings) {
     const { title, body, marker, labels } = f.issue;
-    const hit = known.find((i) => stops(i, marker, bot));
+    const hit = known.find((i) => stops(i, marker, bot, closedStops));
     if (hit || seen.has(marker)) { skipped.push(f.key); line(`skip   ${f.key}: ${hit ? `issue #${hit.number} (${hit.state}) of ${bot} holds the marker` : 'a finding of this file has the same marker'}`); continue; }
     seen.add(marker);
     if (opened.length >= max) { deferred.push(f.key); line(`later  ${f.key}: the limit of ${max} issue(s) for one run is reached`); continue; }
     const cut = String(title).slice(0, 200);
     if (dryRun) { opened.push(f.key); line(`would open   ${f.key}: ${cut}  [${labels.join(', ')}]`); continue; }
     try {
-      if (!labelEnsured) { labelEnsured = true; await ensureLabel(base, key, repo, LABEL, line); }
+      for (const name of [label, ...labels]) {
+        if (ensured.has(name)) continue;
+        ensured.add(name);
+        await ensureLabel(base, key, repo, name, line);
+      }
       const r = await api(base, key, 'POST', `/repos/${repo}/issues`, { title: cut, body, labels });
       if (!r.ok) throw new Error(`GitHub answered ${r.status}`);
       opened.push(f.key);
       line(`opened #${r.data?.number ?? '?'}  ${f.key}: ${cut}${r.data?.html_url ? `  ${r.data.html_url}` : ''}`);
-      const has = (r.data?.labels ?? []).some((l) => (typeof l === 'string' ? l : l?.name) === LABEL);
-      if (!has) { failed.push(f.key); line(`label  ${f.key}: the new issue does not carry the label ${LABEL}; the token may not create labels. Create the label by hand.`); }
+      const has = (r.data?.labels ?? []).some((l) => (typeof l === 'string' ? l : l?.name) === label);
+      if (!has) { failed.push(f.key); line(`label  ${f.key}: the new issue does not carry the label ${label}; the token may not create labels. Create the label by hand.`); }
     } catch (error) {
       failed.push(f.key);
       line(`failed ${f.key}: ${String(error.message).split(key).join('(token)')}`);

package/door/lib/jobs.mjs

@@ -0,0 +1,241 @@
+// `atlas jobs check` and `atlas jobs file`: the watcher of the routines design
+// (its records and security parts).
+//
+//   atlas jobs check --root <repo> --repo <owner/name> [--branch <name>] [--out <file>]
+//   atlas jobs file --findings <file> --repo <owner/name> [--max <n>] [--dry-run]
+//
+// The workflow `.github/workflows/atlas-jobs.yml` runs both, from the default branch, once a day.
+// `atlas tooling` writes it from door/templates/atlas-jobs.yml.
+//
+//   check  reads `jobs: { atlas: [...] }` from atlas.yaml and runs the check of each Atlas job it
+//          names. It reads; it writes no issue. Its job in the workflow holds read permissions only.
+//   file   reads the JSON of the check, keeps the typed fields of each finding and drops the rest, and
+//          opens one `atlas-job` issue for each new finding, through openIssues (issues.mjs).
+//
+// The check envelope (records part, "The check envelope"):
+//   { "jobs": 1, "state": "none" | "found" | "broken", "findings": [ { "job", "key", <typed fields> } ] }
+// A finding holds ids, paths, versions and numbers only. No prose reaches an issue: every line of an
+// issue is Atlas code, and the finding goes into it as one JSON block.
+//
+// A finding is new when no issue of the bot holds its marker, except for one that is closed. A closed
+// issue with the label `handed-over` still stops a new one for 30 days: the runner gave the finding to
+// the tracker. The token is only GITHUB_TOKEN, as for `atlas tests issues`.
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from '../../shape/check.mjs';
+import { api, apiBase, repoOk, openIssues, TOKEN_SHAPE, DEFAULT_BOT, DEFAULT_MAX } from './issues.mjs';
+
+export const JOBS_LABEL = 'atlas-job';
+export const HANDED_OVER = 'handed-over';
+export const HANDED_OVER_DAYS = 30;
+export const JOBS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'jobs');
+export const ENVELOPE = 1;
+export const STATES = Object.freeze(['none', 'found', 'broken']);
+export const MAX_FINDINGS = 50;
+
+const usage = (message) => Object.assign(new Error(message), { usage: true });
+const DAY = 24 * 60 * 60 * 1000;
+
+// A job id, a key, and each typed value. A value is an id, a path, a version or a number: no space and
+// no prose. A key may hold a path, so it takes a slash and a dot.
+const JOB_ID = /^[a-z][a-z0-9-]{0,40}$/;
+const KEY = /^[A-Za-z0-9._/:@+-]{1,200}$/;
+const VALUE = /^[A-Za-z0-9._/:@+-]{1,200}$/;
+const FIELD = /^[a-z][a-z0-9_]{0,40}$/;
+
+// ---------------------------------------------------------------- the Atlas jobs
+
+// Every Atlas job of this package: door/jobs/<id>.yaml.
+export function atlasJobs(dir = JOBS_DIR) {
+  const out = new Map();
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir).sort()) {
+    if (!name.endsWith('.yaml')) continue;
+    const id = name.slice(0, -'.yaml'.length);
+    const job = parseYaml(readFileSync(join(dir, name), 'utf8')) ?? {};
+    out.set(id, { id, ...job, fields: Array.isArray(job.fields) ? job.fields.map(String).filter((f) => FIELD.test(f)) : [] });
+  }
+  return out;
+}
+
+// The Atlas jobs that the repo's atlas.yaml names, read from the checkout of the default branch.
+export function namedJobs(root) {
+  const file = join(root, 'atlas.yaml');
+  if (!existsSync(file)) throw usage(`there is no atlas.yaml in ${root}`);
+  const facts = parseYaml(readFileSync(file, 'utf8')) ?? {};
+  const named = facts.jobs?.atlas;
+  if (named === undefined || named === null) return [];
+  if (!Array.isArray(named)) throw usage('jobs.atlas in atlas.yaml must be a list of job ids');
+  return named.map(String);
+}
+
+// ---------------------------------------------------------------- the check of red-main
+
+// A red run: it ended and did not pass. A cancelled run is not red: a newer push cancels an older run.
+const RED = new Set(['failure', 'timed_out', 'startup_failure']);
+
+// The newest finished run of each workflow on the default branch, from a push to this repo. A run of a
+// pull request, a schedule, or a fork is never read: its event is not push, or its head repo is another.
+export function newestMainRuns(runs, { repo, branch }) {
+  const newest = new Map();
+  for (const run of runs) {
+    if (run?.event !== 'push' || run?.head_branch !== branch || run?.status !== 'completed') continue;
+    if (run?.head_repository?.full_name !== repo || run?.repository?.full_name !== repo) continue;
+    const path = String(run.path ?? '').replace(/@.*$/, '');
+    if (!path || !VALUE.test(path)) continue;
+    const have = newest.get(path);
+    if (!have || Date.parse(run.created_at) > Date.parse(have.created_at)) newest.set(path, run);
+  }
+  return newest;
+}
+
+export async function checkRedMain({ repo, branch, env }) {
+  const base = apiBase(env);
+  const key = env.GITHUB_TOKEN || '';
+  if (!key) throw usage('there is no token: set GITHUB_TOKEN in the environment');
+  const query = `branch=${encodeURIComponent(branch)}&event=push&status=completed&per_page=100`;
+  const r = await api(base, key, 'GET', `/repos/${repo}/actions/runs?${query}`);
+  if (!r.ok || !Array.isArray(r.data?.workflow_runs)) throw new Error(`GitHub answered ${r.status} when the runs of ${branch} were listed`);
+  const findings = [];
+  for (const [path, run] of [...newestMainRuns(r.data.workflow_runs, { repo, branch })].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    if (!RED.has(run.conclusion)) continue;
+    findings.push({ job: 'red-main', key: path, workflow: path, run_id: Number(run.id), head_sha: String(run.head_sha), conclusion: String(run.conclusion) });
+  }
+  return findings;
+}
+
+// The check of each Atlas job, by its `when`. A job whose check is not built yet reads `none` and
+// says so in the notes; it never reads `found` from nothing.
+const CHECKS = { 'red-main': checkRedMain };
+
+export async function jobsCheck({ root, repo, branch = null, env = process.env, jobs = atlasJobs() }) {
+  const named = namedJobs(root);
+  const notes = [];
+  const ran = [];
+  const findings = [];
+  let state = 'none';
+  let mainBranch = branch;
+  for (const id of named) {
+    const job = jobs.get(id);
+    if (!job) { notes.push(`${JOB_ID.test(id) ? id : '(a bad id)'}: no Atlas job has this id`); continue; }
+    const check = CHECKS[job.when];
+    if (!check) { notes.push(`${id}: its check is not built yet`); ran.push({ job: id, state: 'none' }); continue; }
+    try {
+      if (!mainBranch) mainBranch = await defaultBranch({ repo, env });
+      const found = (await check({ repo, branch: mainBranch, env })).map((f) => ({ ...f, job: id }));
+      findings.push(...found);
+      ran.push({ job: id, state: found.length ? 'found' : 'none' });
+    } catch (error) {
+      if (error.usage) throw error;
+      // The message never holds the token: it is built from fixed words and statuses.
+      ran.push({ job: id, state: 'broken' });
+      notes.push(`${id}: broken: ${String(error.message).split(env.GITHUB_TOKEN || '\u0000').join('(token)')}`);
+    }
+  }
+  if (ran.some((one) => one.state === 'broken')) state = 'broken';
+  else if (findings.length) state = 'found';
+  return { jobs: ENVELOPE, repo, branch: mainBranch, state, ran, notes, findings };
+}
+
+async function defaultBranch({ repo, env }) {
+  const r = await api(apiBase(env), env.GITHUB_TOKEN || '', 'GET', `/repos/${repo}`);
+  const name = r.data?.default_branch;
+  if (!r.ok || typeof name !== 'string' || !VALUE.test(name)) throw new Error(`GitHub answered ${r.status} when the default branch was read`);
+  return name;
+}
+
+// ---------------------------------------------------------------- the file job
+
+// Keep a finding only when its job is an Atlas job, its key is typed, and it has at least one field.
+// Keep only the fields that the job lists, and only typed values. Count what is dropped.
+export function typedFindings(envelope, jobs = atlasJobs()) {
+  if (!envelope || envelope.jobs !== ENVELOPE || !STATES.includes(envelope.state) || !Array.isArray(envelope.findings)) {
+    throw usage('the findings file is not the output of `atlas jobs check`');
+  }
+  const kept = [];
+  let dropped = 0;
+  for (const f of envelope.findings.slice(0, MAX_FINDINGS)) {
+    const job = jobs.get(String(f?.job));
+    if (!job || !KEY.test(String(f?.key ?? ''))) { dropped += 1; continue; }
+    const one = { job: job.id, key: String(f.key) };
+    for (const field of job.fields) {
+      const value = f[field];
+      if (typeof value === 'number' && Number.isFinite(value)) one[field] = value;
+      else if (typeof value === 'string' && VALUE.test(value)) one[field] = value;
+    }
+    kept.push(one);
+  }
+  dropped += Math.max(0, envelope.findings.length - MAX_FINDINGS);
+  return { findings: kept, dropped };
+}
+
+// An HTML comment may not hold two hyphens in a row, so the marker spells them another way.
+export const jobMarker = (job, key) => `<!-- atlas-job:${job}:${String(key).replace(/--/g, '-~')} -->`;
+
+// The issue of one finding (records part, "The atlas-job issue").
+export function jobIssue(finding) {
+  const marker = jobMarker(finding.job, finding.key);
+  const body = [
+    `The Atlas watcher found this in the job \`${finding.job}\`. Atlas code wrote this issue. It holds typed fields only.`,
+    '',
+    '```json',
+    JSON.stringify(finding, null, 2),
+    '```',
+    '',
+    'A runner acts on it later. The watcher never edits or closes this issue.',
+    '',
+    marker,
+  ].join('\n');
+  return { title: `atlas-job: ${finding.job} ${finding.key}`.slice(0, 200), body, labels: [JOBS_LABEL, `job:${finding.job}`], marker };
+}
+
+// A closed issue stops a new one only when the runner handed it over in the last 30 days.
+export const handedOverStops = (now = Date.now()) => (issue) => (issue.labels ?? []).some((l) => (typeof l === 'string' ? l : l?.name) === HANDED_OVER)
+  && Number.isFinite(Date.parse(issue.closed_at)) && now - Date.parse(issue.closed_at) <= HANDED_OVER_DAYS * DAY;
+
+export async function fileJobs({ envelope, repo, dryRun = false, max = DEFAULT_MAX, bot = DEFAULT_BOT, env = process.env, line, now = Date.now(), jobs = atlasJobs() }) {
+  const { findings, dropped } = typedFindings(envelope, jobs);
+  if (dropped) line(`dropped ${dropped} finding(s) that are not typed, or that name no Atlas job`);
+  if (envelope.state === 'broken') line('the check reads broken, so a check found nothing it can trust. The run ends red.');
+  const list = findings.map((f) => ({ key: `${f.job}:${f.key}`, issue: jobIssue(f) }));
+  const result = list.length
+    ? await openIssues({ findings: list, repo, dryRun, max, bot, env, line, label: JOBS_LABEL, closedStops: handedOverStops(now) })
+    : (line('no finding: nothing to file.'), { opened: [], skipped: [], deferred: [], failed: [] });
+  return { ...result, broken: envelope.state === 'broken' };
+}
+
+// ---------------------------------------------------------------- the command
+
+export async function jobsCommand({ what, root, repo, branch, out, findings, max, dryRun = false, bot, args = [] }, line, env = process.env) {
+  try {
+    if ([...args, findings, repo, out, branch].some((a) => typeof a === 'string' && TOKEN_SHAPE.test(a))) throw usage('a token must never be an argument; put it in GITHUB_TOKEN');
+    if (!repoOk(repo)) throw usage('give the repo as --repo <owner/name>');
+    if (what === 'check') {
+      if (branch !== undefined && (typeof branch !== 'string' || !VALUE.test(branch))) throw usage('--branch must name a branch');
+      const result = await jobsCheck({ root, repo, branch: branch ?? null, env });
+      const json = `${JSON.stringify(result, null, 2)}\n`;
+      if (out) { mkdirSync(dirname(resolve(out)), { recursive: true }); writeFileSync(resolve(out), json); }
+      line(`jobs check: ${result.state}. ${result.ran.length} job(s) ran, ${result.findings.length} finding(s).${out ? ` Written to ${out}.` : ''}`);
+      for (const one of result.ran) line(`  ${one.job}: ${one.state}`);
+      for (const note of result.notes) line(`  note: ${note}`);
+      if (!out) line(json.trimEnd());
+      return result.state === 'broken' ? 1 : 0;
+    }
+    if (what === 'file') {
+      if (!findings) throw usage('give the check file: --findings <file>');
+      const limit = max === undefined ? DEFAULT_MAX : Number(max);
+      if (!Number.isInteger(limit) || limit < 0) throw usage('--max must be a whole number, 0 or more');
+      const file = resolve(findings);
+      if (!existsSync(file)) throw usage(`the findings file ${file} does not exist`);
+      let envelope;
+      try { envelope = JSON.parse(readFileSync(file, 'utf8')); } catch { throw usage('the findings file is not JSON'); }
+      const r = await fileJobs({ envelope, repo, dryRun: Boolean(dryRun), max: limit, bot: bot || DEFAULT_BOT, env, line });
+      return r.broken || r.deferred.length || r.failed.length ? 1 : 0;
+    }
+    throw usage(`there is no jobs verb "${what ?? ''}". Use check or file.`);
+  } catch (error) {
+    line(`jobs: ${String(error.message).split(env.GITHUB_TOKEN || '\u0000').join('(token)')}`);
+    return error.usage ? 2 : 1;
+  }
+}

package/door/lib/pull-request.mjs

@@ -23,7 +23,7 @@ export const TOOLING_LABEL = 'atlas-helper';
 
 // The only files the tooling writer may write: the check, its workflow, and
 // the pull request template when the repo has none.
-export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH, '.github/pull_request_template.md']);
+export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH, '.github/workflows/atlas-jobs.yml', '.github/pull_request_template.md']);
 
 export class ChangeError extends Error {}
 

package/door/lib/tooling.mjs

@@ -24,6 +24,32 @@ import { PR_TEMPLATE_PATH } from './upkeep.mjs';
 
 export { CHECK_PATH, WORKFLOW_PATH, PACKAGE_CHECK_SOURCE, PR_TEMPLATE_PATH };
 
+// The watcher of the routines design (roadmap R24). The writer puts it into each
+// repo, with the version of this package as its pin. It refreshes a copy whose pin
+// is older than this package, and keeps any other copy: a refresh never moves a
+// repo backwards, and never replaces a hand edit at the same version.
+export const JOBS_PATH = '.github/workflows/atlas-jobs.yml';
+export const PACKAGE_JOBS_SOURCE = 'door/templates/atlas-jobs.yml';
+const VERSION_SLOT = '__ATLAS_VERSION__';
+export function packagedJobsWorkflow(packageRoot) {
+  const full = join(packageRoot, PACKAGE_JOBS_SOURCE);
+  return existsSync(full) ? readFileSync(full, 'utf8').split(VERSION_SLOT).join(packagePackageVersion(packageRoot)) : null;
+}
+const jobsPin = (text) => /@arjunkhera\/atlas@(\d+)\.(\d+)\.(\d+)\b/.exec(text)?.slice(1).map(Number) ?? null;
+const older = (a, b) => { for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] < b[i]; return false; };
+// written, refreshed, unchanged or kept: what the writer does with the watcher.
+function jobsState(root, packageRoot) {
+  const wanted = packagedJobsWorkflow(packageRoot);
+  if (wanted === null) return null;
+  const full = join(root, JOBS_PATH);
+  if (!existsSync(full)) return 'written';
+  const was = readFileSync(full, 'utf8');
+  if (was === wanted) return 'unchanged';
+  const have = jobsPin(was);
+  return have && older(have, jobsPin(wanted)) ? 'refreshed' : 'kept';
+}
+const jobsNeedWrite = (root, packageRoot) => ['written', 'refreshed'].includes(jobsState(root, packageRoot));
+
 // The pull request template (roadmap R8). The writer puts it into a repo that
 // has none, and never replaces a template the repo keeps.
 export const PACKAGE_TEMPLATE_SOURCE = 'door/templates/pull_request_template.md';
@@ -75,7 +101,7 @@ export function mayWrite(root, packageRoot, { replaceUnknown = false, workflowOn
     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 now = status({ root, packageRoot });
-  if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot)) {
+  if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot) && !jobsNeedWrite(root, packageRoot)) {
     throw new ToolingRefusal(`this repo's check is already current. ${readWorkflow(root) === WORKFLOW_TEMPLATE ? '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 });
   }
   if (now.state === 'unknown' && !replaceUnknown && !own) {
@@ -101,6 +127,17 @@ export function write(root, packageRoot, { dryRun = false, replaceUnknown = fals
     }
     rows.push({ path, state, sha256: sha256(contents), was: was === null ? null : sha256(was) });
   }
+  const jobs = workflowOnly ? null : jobsState(root, packageRoot);
+  if (jobs !== null) {
+    const contents = packagedJobsWorkflow(packageRoot);
+    const full = join(root, JOBS_PATH);
+    const was = existsSync(full) ? readFileSync(full, 'utf8') : null;
+    if ((jobs === 'written' || jobs === 'refreshed') && !dryRun) {
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, contents);
+    }
+    rows.push({ path: JOBS_PATH, state: jobs, sha256: sha256(jobs === 'kept' ? was : contents), was: was === null ? null : sha256(was) });
+  }
   const template = workflowOnly ? null : packagedTemplate(packageRoot);
   if (template !== null) {
     const contents = template;
@@ -125,7 +162,7 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
   if (rows.every((row) => row.state === 'unchanged' || row.state === 'kept')) {
     throw new ToolingRefusal('this repo is already current: its Atlas files match the package, so there is nothing to open.', { current: true });
   }
-  const wanted = { ...packagedFiles(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
+  const wanted = { ...packagedFiles(packageRoot), [JOBS_PATH]: packagedJobsWorkflow(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
   return rows
     .filter((row) => row.state !== 'unchanged' && row.state !== 'kept')
     .map((row) => ({
@@ -137,7 +174,9 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
           ? `copied byte for byte from ${PACKAGE_CHECK_SOURCE}, check version ${CHECK_VERSION}, in Atlas ${version}`
           : row.path === PR_TEMPLATE_PATH
             ? `copied from ${PACKAGE_TEMPLATE_SOURCE}, Atlas ${version}; the repo had no pull request template`
-            : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
+            : row.path === JOBS_PATH
+              ? `written from ${PACKAGE_JOBS_SOURCE}, with its pin set to Atlas ${version}`
+              : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
       },
     }));
 }

package/door/templates/atlas-jobs.yml

@@ -0,0 +1,73 @@
+name: atlas-jobs
+# The Atlas watcher: plain code, no model and no secret. `atlas tooling` wrote
+# this file from the Atlas package; do not edit it by hand.
+#
+# It runs once a day from the default branch, and never on a pull request, so
+# a pull request cannot change what it runs. It has two jobs:
+#   check  reads the repo and the CI runs of the default branch. It holds only
+#          read permissions and the run's own token, and no repo secret.
+#   file   holds only issues write. It runs Atlas code on the JSON of the
+#          check job, and files one `atlas-job` issue for each new finding.
+# A job does nothing until atlas.yaml names it under `jobs: { atlas: [...] }`.
+on:
+  schedule:
+    - cron: "17 4 * * *"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: atlas-jobs
+  cancel-in-progress: false
+
+jobs:
+  check:
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      actions: read
+    outputs:
+      findings: ${{ steps.check.outputs.findings }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: Run the check of each job that atlas.yaml names
+        id: check
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          set -euo pipefail
+          # A broken check still hands its JSON on, so the file job reads it and ends the run red.
+          status=0
+          npx --yes --ignore-scripts @arjunkhera/atlas@__ATLAS_VERSION__ jobs check --root . --repo "$GITHUB_REPOSITORY" --branch "$DEFAULT_BRANCH" --out "$RUNNER_TEMP/jobs.json" | tee -a "$GITHUB_STEP_SUMMARY" || status=$?
+          test -s "$RUNNER_TEMP/jobs.json" || { echo "::error::the check wrote no JSON (exit $status)"; exit 1; }
+          echo "findings=$(base64 -w0 < "$RUNNER_TEMP/jobs.json")" >> "$GITHUB_OUTPUT"
+
+  file:
+    needs: check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      issues: write
+    steps:
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: File one issue for each new finding
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          FINDINGS: ${{ needs.check.outputs.findings }}
+        run: |
+          set -euo pipefail
+          printf '%s' "$FINDINGS" | base64 -d > "$RUNNER_TEMP/jobs.json"
+          npx --yes --ignore-scripts @arjunkhera/atlas@__ATLAS_VERSION__ jobs file --findings "$RUNNER_TEMP/jobs.json" --repo "$GITHUB_REPOSITORY" | tee -a "$GITHUB_STEP_SUMMARY"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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/lead/SKILL.md

@@ -104,6 +104,7 @@ set. A test keeps the two lists equal.
 | `atlas tests` | `write` puts the test kit in an area. `check` runs before a merge. `kept` runs the kept tests of a path 1 area and writes their evidence. `proof`, `verdict`, `named`, `covers` and `rerun` read the results of a run. `changed`, `before` and `after` run the test checks of the gate: changed tests, new cases fail on old code, old cases pass on new code. `sweep` and `issues` run the daily sweep |
 | `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
 | `atlas view` | `build --product <id>` makes the project view page of one product, when the owner asks for it or after an Atlas release changes it. Publish it with only the grant the command prints |
+| `atlas jobs` | The `atlas-jobs` workflow calls `check`, then `file`, once a day. A session calls it only to see what the watcher would file: `check`, then `file --dry-run` |
 | `atlas upkeep` | `check` before you ask for a merge: the docs index, dead doc links, and the tracker item a pull request names. The daily upkeep run calls it on the main branch |
 | `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass. On a plan with no rulesets it reports advisory mode. `ready` before each merge. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
 | `atlas judge` | In the fresh-agent test only, as the `atlas:fresh-agent-test` skill says. `seal` after the pick, `brief` to read a sealed ask, `run` for each sealed task, `check` after the grade |

package/skills/sdlc-task/SKILL.md

@@ -148,7 +148,9 @@ A lock is the owner's approval of a short design.
    nothing, so this step is the gate (owner, 24 October 2026).
    1. Right before the merge, run `atlas gate` with the verb `ready`,
       `--repo` and `--pr`.
-   2. A pending check: wait for it. A red or missing check: fix it.
+   2. A pending check: wait for it. A red or missing check: fix it. A
+      branch behind the main branch: merge the main branch in, wait for
+      green, and run `ready` again.
    3. Merge only when it prints READY. Name the head SHA that it read in
       the merge call, so a later push cannot slip in.
    4. Where the verb `apply` set the rulesets, the branch rule holds the

package/skills/upkeep/SKILL.md

@@ -97,7 +97,9 @@ If the tracker cannot be reached, skip this half and say so.
    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.
+   other merge. When the branch is behind the main branch, merge the main
+   branch in, wait for green, and run `ready` again. Otherwise leave it
+   open and say why in the report.
 
 ## The run line
 

package/tests/sweep.mjs

@@ -10,7 +10,8 @@
 //   1  flaky           each scenario/assertion with a `flaky` result, and on how many commits
 //   2  stand-ins       each contract scenario whose newest result is `blocked` (no test instance)
 //   3  no scenario     a pull request (a first-parent change of the base) changed a path that a scenario `covers`,
-//                      and no scenario that covers that path changed in the same pull request
+//                      and no scenario that covers that path changed in the same pull request, or in a later
+//                      pull request of the window
 //   4  quarantine      NOT BUILT. The kit has no quarantine field and no `quarantined` result yet
 //                      (RESULTS in evidence.mjs), so this check reports none and says so. No format is invented.
 //   5  map facts       NOT BUILT. link-check.mjs reads no map format, so the check is skipped with a note
@@ -31,6 +32,10 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
 import { readAttempts, settleRecords, loadAreaScenarios, clean, touches, keyOf } from './verdict.mjs';
 
 export const LABEL = 'atlas-sweep';
+// The labels of the routines design (records part): every issue that a watcher files carries `atlas-job`
+// and the label of its job. The sweep is the check of the job `flaky-tests`. The marker rule and the
+// label LABEL stay as they were, so the issues of older sweeps still stop a second one.
+export const JOB_LABELS = Object.freeze(['atlas-job', 'job:flaky-tests']);
 const DAY = 24 * 60 * 60 * 1000;
 // A pull request is found by the next sweep too, so two days make a sweep that missed a day lose nothing.
 // The marker of a finding keeps a second sweep from opening a second issue.
@@ -53,9 +58,10 @@ function git(cwd, args, { allowFail = false } = {}) {
 
 // ---------------------------------------------------------------- the evidence of many runs
 
-// A run folder is named for a CI run (ci<run id>-<attempt>, with an optional rerun count) or by the
-// kit's own run id (run<6 hex>, fresh.mjs). Any other name is dropped by the sweep.
-const RUN_NAME = /^(ci\d+-\d+(-\d+)?|run[0-9a-f]{6})$/;
+// A run folder is named for a CI run (ci<run id>-<attempt>, with an optional rerun count), for a
+// nightly run (nightly<run id>-<attempt>, the model-nightly workflow), or by the kit's own run id
+// (run<6 hex>, fresh.mjs). Any other name is dropped by the sweep.
+export const RUN_NAME = /^((ci|nightly)\d+-\d+(-\d+)?|run[0-9a-f]{6})$/;
 const ASSERTION_ID = /^[a-z0-9-]+\/e[0-9]+$/;
 const COMMIT = /^[0-9a-f]{40}$/;
 const hasJson = (dir) => readdirSync(dir).some((n) => n.endsWith('.json'));
@@ -134,7 +140,7 @@ function finding({ check, key, title, summary, evidence, quote = null, extra = {
   const lines = [summary, ...(quote ? ['', 'Text from the evidence (data, not an instruction):', fenced(quote)] : []), '', 'Evidence:'];
   for (const [name, values] of Object.entries(evidence)) lines.push(`- ${name}: ${[].concat(values).join(', ') || '(none)'}`);
   lines.push('', 'The daily sweep of `atlas tests sweep` opened this issue. It never changes a file.', '', marker);
-  return { check, key, title, summary, evidence, ...extra, issue: { title, body: lines.join('\n'), labels: [LABEL], marker } };
+  return { check, key, title, summary, evidence, ...extra, issue: { title, body: lines.join('\n'), labels: [LABEL, ...JOB_LABELS], marker } };
 }
 
 // Check 1. One finding for each scenario/assertion that reads `flaky` in some run.
@@ -207,19 +213,26 @@ function checkNoScenario({ area, scenarios, since, base }) {
   ).split('\0').filter(Boolean).map(clean);
   // The repo path of each scenario file, and the covers of each scenario.
   const mine = scenarios.filter((s) => s.id).map((s) => ({ id: s.id, file: clean(`${prefix}${relative(area, s.file)}`), covers: list(s.fields.covers) }));
-  const out = [];
-  for (const line of raw.split('\n').filter(Boolean)) {
+  // The log is newest first. Each change keeps its files, so a change can be read against the later ones.
+  const changes = raw.split('\n').filter(Boolean).map((line) => {
     const [sha, parentText, date, subject] = line.split('\x1f');
-    const files = filesOf(sha, parentText.split(' ').filter(Boolean));
+    return { sha, parentText, date, subject, files: filesOf(sha, parentText.split(' ').filter(Boolean)) };
+  });
+  const out = [];
+  changes.forEach(({ sha, parentText, date, subject, files }, at) => {
+    // A later change of the window (a pull request that came after this one) answers a path when it
+    // edits a scenario that covers that path (roadmap R24 line 5: atlas#173 changed the scenario 19
+    // minutes after atlas#167 changed the code).
+    const later = new Set(changes.slice(0, at).flatMap((one) => one.files));
     const unanswered = [];
     const ids = new Set();
     for (const f of files) {
       const covering = mine.filter((s) => s.covers.some((c) => touches([f], c)));
-      if (!covering.length || covering.some((s) => files.includes(s.file))) continue;
+      if (!covering.length || covering.some((s) => files.includes(s.file) || later.has(s.file))) continue;
       unanswered.push(f);
       for (const s of covering) ids.add(s.id);
     }
-    if (!unanswered.length) continue;
+    if (!unanswered.length) return;
     const paths = unanswered.sort().slice(0, 20);
     const names = [...ids].sort();
     out.push(finding({
@@ -231,7 +244,7 @@ function checkNoScenario({ area, scenarios, since, base }) {
       evidence: { commit: sha, date, paths, scenarios: names, parents: parentText.split(' ').filter(Boolean).length },
       extra: { commit: sha },
     }));
-  }
+  });
   return out;
 }